Flare Getting Started Guide

Transcription

Getting Started Guide
Version 7.0
Scan this QR code to open the
online Help on your mobile device.
Copyrights
Copyright 2011 MadCap Software. All rights reserved.
Information in this document is subject to change without notice. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used
or copied only in accordance with the terms of those agreements. No part of this publication may be
reproduced, stored in a retrieval system, or transmitted in any form or any means electronic or
mechanical, including photocopying and recording for any purpose other than the purchaser's personal use without the written permission of MadCap Software.
MadCap Software
7777 Fay Avenue
La Jolla, California 92037
858-320-0387
www.madcapsoftware.com
Contents
CHAPTER 1 Introduction
1
How It Works
Major Benefits
Getting Additional Help
2
4
5
CHAPTER 2 Touring the Workspace
7
Main Sections of the Interface
XML Editor
Window Panes
Project Organizer
Content Explorer
Menus
Global Toolbars
Local Toolbars
Status Bar
Customizing the Workspace
Window Layouts
8
9
11
12
13
14
14
18
20
21
22
CHAPTER 3 Starting Projects
25
Ways to Start Projects
Files
Creating a New Project
Creating a Project by Importing a RoboHelp Project
Creating a Project by Importing an HTML Help Project (HHP)
Creating a Project by Importing CHM Files
Creating a Project by Importing Word Documents
Creating a Project by Importing FrameMaker Documents
Creating a Project by Importing DITA File Content
Importing a Project from Source Control
Opening a Project
Global Project Linking—Importing Files from Other Projects
CHAPTER 4 Adding Stuff to Projects
What You Can Add to a Project
Topics
Audio
Browse Sequences
Characters and Symbols
Context-Sensitive Help
Equations
26
27
28
30
31
32
33
38
48
51
53
54
59
61
64
78
86
94
97
125
-i-
MADCAP FLARE
External Resources
Footnotes
Glossaries
Indexes
Master Pages
Movies
Navigation Links
Page Layouts
Pictures
QR Code
Rulers
Scripts
Search
SharePoint Integration
Snippets
Tables
Tables of Contents
Text Boxes
Variables
CHAPTER 5 Making It Look Good
Styles and Style Sheets
Local Formatting
Auto-Numbers
Fonts
Headings
Lists
Object Positioning
Paragraph Formatting
Skins
CHAPTER 6 Developing Outputs
Important Concepts
Tasks Associated with Outputs
Determining the Output Type
Changing the Output Type for a Target
Adding Targets
Renaming Targets
Setting a Primary Target
About Condition Tags
Creating Condition Tags
Applying Condition Tags to Content
Associating Condition Tags with Targets
Editing Target Settings
- ii -
127
138
141
147
178
182
197
275
283
295
299
300
302
310
322
331
338
346
352
361
362
363
364
381
382
383
400
403
405
413
414
417
419
432
433
435
436
437
439
441
447
448
CHAPTER 7 Building Output
457
Ways to Build Output
Building the Primary Target
458
459
Table of Contents
Building a Single Target
Building Output Using a Batch Target
Viewing Output
CHAPTER 8 Distributing Output
Ways to Distribute Output
Creating Publishing Destinations
Associating Publishing Destinations with Targets
Publishing Output to Destinations
Index
460
461
468
469
470
480
483
484
487
- iii -
MADCAP FLARE
- iv -
Welcome to MadCap Flare—the first native XML content authoring application designed for singlesource, multi-channel publishing. Flare is the flagship product in MadCap Software’s integrated
suite of next generation authoring software. Like the other products in this suite, Flare is a flexible,
open-architecture application that produces XML files with Unicode support for all left-to-right languages.
With Flare you can deliver content for user Help systems, sales and marketing, training and eLearning, technical support, policies and procedures, and knowledge bases—in print, online, and on the
Web. Flare is designed for authors who need a quick and easy way to compose content with all of
the re-use and flexibility of the XML format. Fortunately, no knowledge of XML is required in order
to use Flare. This allows you to focus on creating content and keep pace with the industry evolution
to XML, without having to learn any programming.
This chapter discusses the following:
How It Works
2
Major Benefits
4
5
-1-
MADCAP FLARE
How It Works
As the following diagram shows, the Flare workflow can be boiled down to just a handful of steps.
The real strength of Flare is that you can maintain your content in one place but generate all of it (or
portions of it) in whatever output format works best for you.
-2-
Following are the basic steps for developing a project:
1. Start projects Create a project from scratch, or start a project by importing existing content
from a variety of sources. See "Starting Projects" on page 25.
2. Add "stuff" Add information and elements to your project, such as topics, text, a table of
contents, cross-references, navigation, page layouts, and all of the other "stuff" necessary to
help your end users. See "Adding Stuff to Projects" on page 59.
3. Make your project look good Through the use of elements such as style sheets and skins,
you can develop a look and feel for your output. See "Making It Look Good" on page 361.
4. Develop outputs Decide the type(s) of output format(s) you want to generate (DotNet Help,
HTML Help, WebHelp, WebHelp Plus, WebHelp AIR, WebHelp Mobile, Adobe PDF, XHTML,
Microsoft XPS, Microsoft Word, Adobe FrameMaker, or DITA), and design targets accordingly
to meet your needs. See "Developing Outputs" on page 413.
5. Build output Generate the file(s) that you will deliver to users. See "Building Output" on
page 457.
6. Distribute output Make the output accessible to your end users. See "Distributing Output"
on page 469.
-3-
MADCAP FLARE
Major Benefits
Following are some of the major benefits of using Flare.
n
Efficient topic-based authoring and single-sourcing Flare was designed around the
concept of single-sourcing, which essentially means that you can create content once and
reuse it in many places and in many ways. In Flare the focus is on developing pieces of information (topics) that are useful to readers, rather than focusing on creating one enormous document. In other words, you can first focus on the content and later worry about how it should
be delivered to users; the two concepts are separate. Topic-based content development allows
you to take full advantage of Flare's many powerful single-sourcing features. After you are finished creating topics, you can send them out individually for review (another benefit of small
topics), and when the review process is finished, you can decide how to use the topics in the
output.
E X AMPLE
Let 's say y ou writ e 200 t op ics in y ou r p roject . You might send some of t hese
t op ics t o one p erson for rev iew, and ot her t op ics t o a d ifferent p erson for
rev iew. When t hat is finished and y ou are read y , y ou cou ld ou t p u t 100% of t he
t op ics t o one manu al, 80% of t hem int o a second manu al, and 4 5% of t hem
int o a t hird manu al. Ju st p ick and choose t he cont ent y ou need for each manual.
-4-
n
Project management and team authoring Flare provides several features that can be
used to manage your project and enhance team authoring. This includes features such as
source control, SharePoint integration, linking to external resources, topic reviews and contributions, file tagging, and more.
n
Global Project Linking You can import content and project files contained in another
Flare project, thus allowing you to maintain the information in one location but reuse it in
any other project. When you use this feature to import files, you can include or exclude particular types of files (e.g., topics, snippets, style sheets, glossaries, targets), specific individual
files, or files that have certain condition tags applied. Simply use the include/exclude methods that work best for you.
n
Snippets and variables Sometimes you might have very small pieces of content or text
that need to be reused in many topics. Rather than retyping or copying and pasting that content, you can create snippets and variables and maintain the information in just one place.
n
DITA You can import content from DITA files, work with relationship tables, and generate
DITA code output. In addition, you can edit style classes that result from imported DITA elements.
n
Build output using a batch target You can generate and/or publish multiple targets in a
batch from the user interface, perhaps scheduled to run at a specific time.
n
Easily translate content with MadCap Lingo integration Flare is tightly integrated
with MadCap Lingo, which was especially designed to make it as easy as possible to translate
a Flare project into other languages.
You can use any of the following resources for additional help not provided in this manual.
Downloadable Manuals
n
Quick Guide This manual is a very shortened version of the Getting Started Guide. It is
sort of a CliffsNotes® version, ideal for individuals who simply want brief explanations of the
most vital parts of the Flare process. For steps and details not found in this manual, please
refer to the Getting Started Guide or the online Help.
madcapsoftware.com/documentation/FlareV7/FlareQuickGuide.pdf
n
What's New Guide This manual describes the features that are new in this version of Flare.
madcapsoftware.com/documentation/FlareV7/FlareWhatsNewGuide.pdf
n
Key Features Guide This manual describes the key features that make Flare unique.
madcapsoftware.com/documentation/FlareV7/FlareKeyFeaturesGuide.pdf
n
Transition from RoboHelp Guide This manual is designed to provide information to
RoboHelp users who are making the transition to Flare.
madcapsoftware.com/documentation/FlareV7/FlareTransitionRHGuide.pdf
n
Transition from FrameMaker Guide This manual is designed to provide information to
FrameMaker users who are making the transition to Flare.
madcapsoftware.com/documentation/FlareV7/FlareTransitionFMGuide.pdf
n
Styles Guide This manual tackles the subject of formatting content in a Flare project
through the use of styles. Basic explanations, examples, and detailed steps are provided.
madcapsoftware.com/documentation/FlareV7/FlareStylesGuide.pdf
n
Printed Output Guide This manual provides detailed steps of the tasks involved with producing print-based output (Adobe PDF, XHTML, Microsoft XPS, Microsoft Word, Adobe
FrameMaker).
madcapsoftware.com/documentation/FlareV7/FlarePrintedOutputGuide.pdf
n
WebHelp Plus Guide This manual provides an overview of WebHelp Plus and detailed
steps on setting it up.
madcapsoftware.com/documentation/FlareV7/FlareWebHelpPlusGuide.pdf
-5-
MADCAP FLARE
Online Help
You can open the online Help system and look for the information you need.
n
Dynamic Help pane Select Help>Dynamic Help or press CTRL+F3. The Dynamic Help
pane opens (by default on the right side of the interface) and will display the appropriate
Help topics as you click in different areas of the workspace.
n
Context-sensitive Help without the Dynamic Help pane Press F1 to open the appropriate topic for the active area of the workspace.
n
Table of contents Select Help>Contents or press CTRL+ALT+F1 This opens the online
Help TOC (by default on the left side of the interface). Navigate through the TOC books and
pages to find the information you need. When you click a topic page, it opens.
n
Index Select Help>Index or press ALT+F1 This opens the online Help index (by default on
the left side of the interface). Navigate through the index to find keywords for the information
you need. Also, open the Index Results window pane by selecting Help>Index Results or
pressing ALT+SHIFT+F2. When you click a keyword in the index, the associated topic links
are listed in the Index Results window pane. Click any of the links to open a specific topic.
n
Search feature Select Help>Search or press CTRL+F1 . This opens the Help Search window pane (by default on the left side of the interface). Enter one or more keywords in the field
and click Search. Links to topics containing those keywords are listed below. When you click
a topic link, that topic displays in the workspace.
n
Glossary Select Help>Glossary. This opens the Help glossary (by default on the left side of
the interface). Click any of the terms in the glossary to see a definition.
Video Tutorials And Movies
From the Start Page, you can click Browse Video Tutorials. This opens an online Help topic with
links to various video tutorials and movies, which are designed to guide you through various tasks
and features in Flare. You can also open this topic by selecting Help>Video Tutorials.
Knowledge Base
You can browse the online Knowledge Base for articles covering common support issues.
http://kb.madcapsoftware.com/
Peer-to-Peer Online Forums
You can visit the online forums to learn from other users or share your own expertise.
http://forums.madcapsoftware.com/
Contact Flare Support
You can contact the Flare support team and get answers to your specific support issues.
http://madcapsoftware.com/support/
-6-
CHAPTER 2 Touring The Workspace
Flare's workspace is flexible, uses a modern Multiple Document Interface (MDI), and gives you several options to work the way that you want.
Main Sections of the Interface
8
XML Editor
9
Window Panes
11
Project Organizer
12
Content Explorer
13
Menus
14
Global Toolbars
14
Local Toolbars
18
Status Bar
20
Customizing the Workspace
21
Window Layouts
22
-7-
MADCAP FLARE
Main Sections Of The Interface
The user interface consists of the following major sections:
n
Left The left side of the Flare interface is the default location for many different explorers and
window panes (e.g., Content Explorer, Project Organizer), which can be used to create, open,
and view various elements in the project.
n
Middle The large middle section of the Flare interface is the default location for the many
editors in Flare (e.g., XML Editor, TOC Editor, Stylesheet Editor), which are used to enter
and design the vast majority of the content for your project. It also displays the Start Page,
which is used for quickly performing high-level tasks and accessing information.
n
Right The right side of the Flare interface (like the left side) is the default location for many
different window panes (e.g., Styles window pane).
n
Bottom The bottom area of the Flare interface is the default location for yet more window
panes.
The explorers and window panes on the edges of the interface are used to support the work that you
do in the middle. You have the flexibility to close or move elements around as you like, so it is not
-8-
mandatory that every window pane remain permanently in its default location. In addition to the
main areas, the interface also consists of menus, global toolbars, and local toolbars.
For a video demonstration of these areas, see the online Help.
XML Editor
The XML Editor is the primary editor that you will use in Flare. This editor is used to enter, modify,
and format the content for topics (page 64) that users see in the output. Not only is this editor used
for topics, but it is also used for working with snippets (page 322) and master pages (page 178).
Although this editor lets you produce XML files, you do not need to know anything about XML to
use it. There are two modes that you can use in this editor—Web Layout mode (shown in the image
below) or Print Layout mode.
-9-
MADCAP FLARE
The XML Editor provides structure bars above and to the left of the content area in order to provide
a visual display of the topic tags and structure. These bars provide you with information about your
content without having to view all of the tags mixed within the text. There are two types of structure
bars: tag bars and span bars.
Not only do structure bars let you see the tags for content, but you can also perform numerous tasks
by using them. If you right-click on a structure bar, a context menu opens. From the menu, you can
select from several options to take action on the content associated with that structure bar.
Do you need to use structure bars? No, not necessarily. You can turn them off if you want. However,
in time you will most likely find them to be quite useful.
Do you need to know XML or HTML in order to use them? It helps. The more knowledge you have of
XML and HTML, the more useful the bars will be. However, even with little or limited XML/HTML
knowledge, you may find these bars to be somewhat intuitive by comparing them to the corresponding text in your topics. For more information see the online Help.
- 10 -
Window Panes
Flare has numerous window panes in the interface that are used for a variety of purposes. The two
panes that you are likely to use most are the Project Organizer and Content Explorer. Some of these
panes are located by default on the left side of the workspace, some on the right side, and some at
the bottom. Some elements are contained in window panes as opposed to dialog windows because
they contain features that you would want to have easy access to as you work in an editor. If more
than one window pane is open on either side, the panes are organized in an accordion structure.
This means that they are stacked on top of each other, with the active window pane displayed "in
front" of the other panes. Accordion bars for each window pane are located at the bottom, and you
can click any bar to bring that particular window pane "in front" so that you can work in it.
- 11 -
MADCAP FLARE
Project Organizer
The Project Organizer, just as it sounds, is used to hold all of your project-related files—such as files
for browse sequences, publishing destinations, skins, targets, tables of contents, and variables.
- 12 -
Content Explorer
The Content Explorer is used to hold all of your content-related files—such as topics, images, snippets, and style sheets. In order to keep your topics organized and easier to find, you can create subfolders in the Content Explorer and move topics into them. Non-topic content files, such as images
and style sheets, are stored by default in the Resources folder, although you can place them anywhere else in the Content Explorer if you want. You can also create subfolders to organize the files in
the Resources folder.
- 13 -
MADCAP FLARE
Menus
Flare's user interface includes a menu bar at the top of the program window, containing several
menu options. Three of the more unique menu items are the "Project," "Review," and "Build" menus.
The Project menu can be used to add most of the different kinds of features available in Flare (e.g.,
topics, page layouts, style sheets, snippets, variables, targets). The Review menu lets you perform
various tasks when it comes to sending topics out for review. The Build menu lets you build (i.e.,
generate), view, and publish output from the project.
Global Toolbars
Flare has multiple global toolbars ("global" meaning they are always available at the top of the user
interface, regardless of the type of document, editor, or window pane you are working on at the
moment).
Standard Toolbar
Tools in the Standard toolbar let you perform basic functions, such as Save, Cut, Copy, Paste, Undo,
and Redo. There are also shortcut buttons for performing source control functions, as well as sending documents to other applications (e.g., opening a topic's true code in Notepad in order to edit the
tags). To see this toolbar you can select View>Toolbars>Standard.
- 14 -
Text Format Toolbar The Text Format toolbar lets you quickly apply formatting to content in your topics and other files.
To see this toolbar, click
in the XML Editor, or select View>Toolbars>Text Format.
- 15 -
MADCAP FLARE
Project Toolbar
Tools in the Project toolbar provide shortcut buttons for some of the most common tasks in Flare,
such as building and viewing targets, opening the primary target, and adding topics. To see this
toolbar, select View>Toolbars>Project.
- 16 -
Review Toolbar
The Review toolbar lets you quickly perform tasks that are part of the review workflow. This includes
sending and importing topics for review, inserting and working with annotations, as well as tracking
changes. To see this toolbar select View>Toolbars>Review.
- 17 -
MADCAP FLARE
Local Toolbars
These are toolbars that are intended for a particular editor or window pane. For example, the XML
Editor contains not only one, but two, local toolbars—one at the top of the editor and the other at
the bottom. In fact, the bottom toolbar changes depending on whether you are in Web Layout mode
or Print Layout mode. The top local toolbar includes a shortcut button for inserting a hyperlink,
because the XML Editor is where you would use that feature (as opposed to, say, the Stylesheet
Editor). Most editors and window panes in Flare contain at least one local toolbar. Following are the
local toolbars in the XML Editor.
- 18 -
Top Toolbar In XML Editor
Following is the local toolbar that appears at the top of the XML Editor, with a few of the most
important buttons explained.
Bottom Toolbar In XML Editor (Web Layout Mode)
Following is the local toolbar that appears at the bottom of the XML Editor when you are working in
Web Layout mode, with a few of the most important buttons explained.
- 19 -
MADCAP FLARE
Status Bar
At the very bottom of the interface is a status bar, which can be turned on or off by selecting
View>Status Bar . The most notable use for the status bar is to see the progress of MadCap
Analyzer as it scans your project. MadCap Analyzer is built in to Flare, and a more robust full version of it is available separately as well. Its purpose is to scan your project for possible issues or suggestions and report them back to you. The larger your project, the longer the amount of time to scan
your project will take. You can continue working while the scan takes place. However, when you
attempt to perform certain tasks (such as viewing the file dependencies of a topic), you must wait
until the scan finishes for the task to complete. For more information about Analyzer, see the online
Help.
- 20 -
Customizing The Workspace
One of the benefits of Flare's user interface is that it is flexible and easy to customize to meet your
needs. Following are some of the ways you can customize the workspace.
For a video demonstration, see the online Help.
Moving, Docking, And Floating Window Panes
Simply because a window pane is attached to the left or right side of the program window by
default, this does not mean it has to stay there.
n
Moving window panes You can move a window pane by clicking the "Drag Pane" section
(located in the upper-left corner of the window pane) and dragging the window pane where
you want it.
n
Floating window panes If you drop the window pane at a random location in the program
window, it becomes a "floating" window. (You can also create a floating window by clicking in
the element and selecting Window>Floating.)
n
Docking window panes "Docking" a window pane means to "attach it" to a particular part
of the program window. To do this, move the floating window pane by clicking in the title bar
of the window pane, drag it to the edge where you want to dock it, and drop it onto one of the
blue arrows or bulls eyes that appear in the interface.
n
Send to main dock You can quickly move a window pane to the main area of the interface
(the middle, where the editors are displayed). Simply right-click on the title bar of the window pane and select Send To Main Dock.
Auto-Hiding Window Panes
In the top-right corner of every window pane, you will see a small button that looks like a pin . If
you click this button, the window pane is hidden (or "pinned" to the edge of the program window).
However, you can still see the title of the window pane along the edge of the program window.
When you hover over the title, the window pane temporarily displays again until you move the
mouse off the window pane. Click the button again to "un-pin" the window pane.
Resizing User Interface Elements
You can easily resize the program window, dialog windows, and floating window panes in Flare by
clicking the edge of the element and dragging the mouse to the desired size. You can also resize
drop-down menus in the same way.
- 21 -
MADCAP FLARE
Window Layouts
When you move window panes, explorers, or editors around in the Flare interface, the configuration
(or "layout") of the workspace is changed. You can do several things with layouts, including the following:
n
Save You can save different layouts of the interface, in case you want to use them for different purposes.
E X AMPLE
Let 's say t hat y ou want t o u se one lay ou t for creat ing t op ics and ad d ing cont ent , and anot her lay ou t for ind exing. In y ou r t op ics lay ou t , y ou might want
t o hav e only t he Project Organizer and C ont ent Exp lorer op en on t he far left .
In y ou r ind exing lay ou t , y ou might want t o hav e t he Ind ex wind ow p ane op en
on eit her t he far right or far left . You cou ld sav e one lay ou t and name it "Top ics, " and t hen sav e t he ot her lay ou t , naming it "Ind exing. "
n
Auto-save You can automatically save the layout of the workspace when you exit Flare. The
next time you launch Flare, that same layout will be displayed.
n
Select You can quickly change the configuration of your workspace by selecting a window layout that you have saved previously.
n
Reset You can return the workspace configuration to the original layout that you saw when
you first installed and launched Flare.
n
Reload You can return the workspace to the saved configuration of the layout. In other
words, if you are working in a particular layout and have opened different interface elements
or moved interface elements around, you can select this option to go back to the saved configuration.
n
Lock You can freeze a window layout so that the window panes and editors cannot be moved
floated or docked to different areas of the interface.
n
Delete You can open the Manage Window Layouts dialog, which lets you select or delete an
existing layout.
How to save a window layout
1. Configure the workspace how you want it.
2. Select Window>Layouts>Save Window Layout As.
3. In the Rename Window Layout dialog, enter a name for the layout.
4. Click OK.
How to auto-save a window layout
n
- 22 -
Select Window>Layouts>Auto-save Layout.
How to select a saved window layout
n
Select Window>Layouts>Select Layout>[Name of Layout].
How to reset the window layout
n
Select Window>Layouts>Reset Window Layout.
How to reload the window layout
n
Select Window>Layouts>Reload Window Layout.
How to lock a window layout
n
Select Window>Layouts>Lock Window Layout.
How to delete a window layout
1. Select Window>Layouts>Layouts.
The Manage Window Layouts dialog opens.
2. Select the layout that you want to delete.
3. Click Delete.
4. Confirm the deletion by clicking OK.
5. Click Close.
- 23 -
MADCAP FLARE
- 24 -
The first step in developing a project after you launch Flare is to start a project.
Ways to Start Projects
26
Files
27
Creating a New Project
28
Creating a Project by Importing a RoboHelp Project
30
Creating a Project by Importing an HTML Help Project (HHP)
31
Creating a Project by Importing CHM Files
32
Creating a Project by Importing Word Documents
33
Creating a Project by Importing FrameMaker Documents
38
Creating a Project by Importing DITA File Content
48
Importing a Project from Source Control
51
Opening a Project
53
Global Project Linking—Importing Files from Other Projects
54
- 25 -
MADCAP FLARE
Ways To Start Projects
You can start a project in one of several ways.
- 26 -
n
Create a new project from scratch Use the Start New Project Wizard to create a new
project, basing it on a factory template or one that you have created. See "Creating a New
Project" on page 28.
n
Import RoboHelp project Create a new project by importing a RoboHelp project (MPJ or
XPJ file). See "Creating a Project by Importing a RoboHelp Project" on page 30.
n
Import HTML Help project (HHP) Create a new project by importing an HTML Help
project (HHP file). See "Creating a Project by Importing an HTML Help Project (HHP)" on
page 31.
n
Import HTML Help file (CHM) Create a new project by importing an HTML Help file
(CHM file). See "Creating a Project by Importing CHM Files" on page 32.
n
Import Microsoft Word Create a project by importing Microsoft Word documents. In addition, after you create a project (using any method), you can create new topics in that project
by importing Word documents. See "Creating a Project by Importing Word Documents" on
page 33.
n
Import Adobe FrameMaker Create a project by importing Adobe FrameMaker documents. Because you can import the source FrameMaker BOOK and FM files (rather than just
MIF files), Flare has full access to FrameMaker variables, conditionals, auto-numbering, and
so on. This means that those features are converted to Flare seamlessly. In addition, after you
create a project (using any method), you can create new topics in that project by importing
FrameMaker documents. See "Creating a Project by Importing FrameMaker Documents" on
page 38.
n
Import DITA content Create a project by importing DITA file content. When you do this,
the DITA elements are converted to HTML tags (and if you later generate DITA output, they
are then converted back to DITA elements). In addition, after you create a project (using any
method), you can create new topics in that project by importing DITA file content. See "Creating a Project by Importing DITA File Content" on page 48.
n
Import from source control Import a Flare project that has been added to a source control application, such as Microsoft Visual SourceSafe, Microsoft Team Foundation Server, or
Apache Subversion. See "Importing a Project from Source Control" on page 51.
n
Open a project Start a project by opening an existing one. See "Opening a Project" on page
53.
Files
When you create a new Flare project, a file with an .flprj extension is automatically generated (e.g.,
MyProject.flprj). This is the main file for the project and is stored at the root level of the project
folder in Windows. You can open the project in Flare by double-clicking this file.
In addition to the main FLPRJ file, there are numerous other files that are part of your Flare project.
All Flare files are separate XML documents—topics, TOCs, browse sequences, page layouts, targets,
skins, snippets, glossaries, destinations, condition tag sets, variable sets, and more. This means that
Flare projects are completely open, transparent, and accessible. When you look at the location in
Windows where you stored your Flare project, you will see the main FLPRJ file, plus a handful of
folders that hold the other files described below. You will always see Content and Project folders
(which hold content and project files, respectively). In addition to those, you might see the following
folders, depending on the actions you take in your project: Analyzer, FileSync, Output, SourceControl.
n
Content files These files are created as you add new topics or resources such as pictures,
style sheets, or snippets within the project. These files are stored in the Content Explorer.
n
Project files These files are created as you add certain features to the project and develop
outputs (targets). When you develop a project, you probably want it to have certain features
and characteristics. For example, you might want to include variables or a glossary. When
you add and develop elements such as these in Flare, specific project files are created for you
so that the final output knows how to look and behave. One of the greatest benefits of Flare is
that these files are independent, rather than being built into the main FLPRJ file or part of
some proprietary database file. This means that they can easily be used in other projects,
shared with other authors, and modified with any XML editor. These files are stored in the
Project Organizer.
n
Analyzer files These files are automatically created with each Flare project if you also have
Microsoft SQL Server Compact installed. They are database files used behind the scenes when
you use Analyzer features in Flare. You do not need to do anything with these files.
n
FileSync files These files are automatically created when you create mappings between external files and copies in your project (e.g., if you are working with external resources or SharePoint integration). You do not need to do anything with these files.
n
Output files These files are created when you build the final output for a Flare project. What
is the ultimate goal of your Flare project? It is to produce an end result that you can provide
to your users. This might be a single Help system, a group of Help systems, printed documentation, or a combination of these. That is the purpose of output files. They are automatically created when you build a project in Flare. You can then distribute these files to end
users. See "Building Output" on page 457.
n
Source control files These are files created by Flare if you bind your project to source control.
- 27 -
MADCAP FLARE
Creating A New Project
Following are the steps for creating a new project from scratch.
How to create a new project
1. Select File>New Project. The Start New Project Wizard opens.
2. In the Project name field, type an appropriate name for your project.
3. By default, a path to the My Documents\My Projects folder on your hard drive is entered in
the Project folder field. (Flare creates the My Projects folder when you install the program.)
All subfolders and files related to the project will be placed in this folder as you work on the
project. Continue with the next step, unless you want to have your project files placed in a different folder. If so, do the following:
a. Click
. The Browse For Folder dialog opens.
b. Navigate to the folder you want, select it, and click OK.
4. (Optional) If you want to integrate the new Flare project with a source control application,
select Bind to Source Control. Then click Next.
5. (Optional) If you have selected the "Bind to Source Control" option, click Bind Project. Then
in the Bind Project dialog, complete the fields, depending on the source control application
being used. When you are finished, click Next.
Note: If you have elected to bind the project to source control but do not complete the
source control fields, the Finish button in the wizard is disabled.
6. Select the language that you want to use for the project. Then click Next.
7. In the Source area select one of the following:
n
New from template This lets you choose either a factory template file or one of your
own customized template files as a starting point. The new file will take on all of the
settings contained in the template. If you want to use a factory template provided by
Flare, expand the Factory Templates folder and click on a template file. If you want
to use your own customized template file, expand the appropriate folder and click on a
file. For more information about templates, see the online Help.
Note: In some dialogs and wizards you can click the Manage Templates button
if you want to open the Template Manager. This lets you manage any of your
template files (e.g., add new templates, enter descriptions for templates). For more
information see the online Help.
n
- 28 -
New from existing This lets you choose an existing file of the same type—that
you've already created and stored somewhere—as a starting point for your new file. As
with template files, your new file will take on all of the settings contained in the file
you select. To use this option, click the browse button
, use the dialog that opens to
find a file, and double-click it.
8. Click Next.
9. In the Available Targets area, select the primary target for your project.
10. Click Finish.
- 29 -
MADCAP FLARE
Creating A Project By Importing A RoboHelp Project
Following are the steps for creating a project by importing a RoboHelp project.
How to import a RoboHelp project
1. Select File>Import Project>RoboHelp Project.
2. In the dialog that opens, browse for and double-click the RoboHelp project file (MPJ or XPJ
file) to be imported.
The Import Project Wizard opens.
3. In the Project name field, type a name for the new Flare project that will be created after
you import the RoboHelp project.
4. In the Project folder field, either accept the default location for the new project or click
to browse for and select a folder.
5. Click Next.
6. (Optional) Select Convert all topics at once if you want Flare to immediately convert all
of your topic files to XHTML.
If you remove the check mark from the box, Flare imports the topic files as they are. When
you try to open an imported topic in Flare, a message asks if you want to convert it to XML.
Also, if this option is not selected, Flare will not import index keywords from the source files.
7. (Optional) Select Convert inline formatting to CSS styles if you want Flare to create
new styles based on any "local" formatting that exists in the RoboHelp project files.
E X AMPLE
If y ou hav e ap p lied bold and it alic format t ing t o some t ext (wit hou t u sing a
st y le), Flare will creat e a new st y le based on t hat format t ing.
8. Click Next.
9. Select a language for the project.
10. Click Finish. A message tells you that the project was converted successfully and will be
opened.
11. Click OK.
Note: For additional information, you can download the Transition from RoboHelp Guide:
madcapsoftware.com/support/files/documentation/FlareV7/FlareTransitionRHGuide.pdf
- 30 -
Creating A Project By Importing An HTML Help Project (HHP)
Following are the steps for creating a project by importing an HTML Help project (HHP file).
How to import an HTML Help project (HHP)
1. Select File>Import Project>HTML Help Project (HHP).
2. In the dialog that opens, browse for and double-click the HTML Help file (HHP file) to be
imported.
you import the HTML Help project.
5. Click Next.
you try to open an imported topic in Flare, a message asks if you want to convert it to
XHTML. Also, if this option is not selected, Flare will not import index keywords from the
source files.
new styles based on any "local" formatting that exists in the HTML Help project files.
E X AMPLE
8. Click Next.
10. Click Finish.
A message tells you that the project was converted successfully and will be opened.
11. Click OK.
- 31 -
MADCAP FLARE
Creating A Project By Importing CHM Files
Following are the steps for creating a project by importing an HTML Help (CHM) file.
How to create a project by importing an HTML Help (CHM) file
1. Select File>Import Project>HTML Help File (CHM).
2. In the dialog that opens, browse for and double-click the CHM file to be imported.
you import the CHM file.
to find and select a folder.
5. Click Next.
you try to open an imported topic in Flare, a message asks if you want to convert it to
XHTML. Also, if this option is not selected, Flare will not import index keywords from the
source files.
new styles based on any "local" formatting that exists in the HTML Help file.
E X AMPLE
8. Click Next.
10. Click Finish.
A message tells you that the project was converted successfully and will be opened.
11. Click OK.
- 32 -
Creating A Project By Importing Word Documents
Following are the steps for creating a project by importing Word documents.
How to create a project by importing Word documents
1. Select File>Import Project>MS Word Documents.
The Import Microsoft Word Wizard opens.
2. Do one of the following:
n
If you have not yet imported Word documents that you want to re-use, click Next.
OR
n
If you have imported Word documents into the project previously, Flare has created an
FLIMP file containing that data and stored it in the Project/Imports folder. If you want
to re-use these same documents or settings, click Saved Import Data. In the Open
dialog, navigate to the FLIMP file and double-click it.
3. Click the Add Files button to find and select Word documents on your computer to include
in the import. You can select DOC, DOCX, or RTF files.
Note: DOCX is Microsoft Word's platform-independent, open XML format. You must
have Microsoft Word 2007 installed in order to import this file type.
4. (Optional) You can use the various options on this page as necessary.
n
Open File This opens the Word document that is selected in the list.
n
Link Generated Files To Source Files This creates a connection between the original Word documents and the files that are created as a result of the import. This is
useful if you want to continue editing the content in the original Word documents,
instead of editing in the Flare project. Flare recognizes when changes have been made
to the source documents and reminds you to re-import the documents to ensure the
Flare project also reflects the changes.
If you use this option, a link icon is added to the top of a linked file in the Flare interface. This lets you know that you need to edit the source file, rather than editing this
file. If you remove the connection to the source file, this icon no longer displays on the
file. Please note that if you have bound the project to source control, the icons used for
source control take precedence over the link icon.
n
Move Up This moves the selected document higher in the list (if you have more than
one document to import). The document at the top is used for the name of the content
folder holding the imported topics in Flare. Also, the order determines how the
imported documents are arranged in the Flare TOC that is created as a result.
n
Move Down This moves the selected document lower in the list (if you have more
than one document to import).
n
Remove This removes the selected document(s) from the list.
- 33 -
MADCAP FLARE
5. Click Next.
The Word documents are scanned and the next page of the wizard opens.
you import the Word documents.
8. Click Next.
The paragraph styles used in the Word documents are shown on the left side of the wizard
page ("Used Word Styles").
Note: You can skip the rest of the wizard pages by clicking Finish.
9. (Optional) If you want Flare to split the Word documents into smaller topics based on any of
the styles shown on the left side of the page ("Used Word Styles"), double-click that style to
move it to the right side of the page ("New Topic Styles").
E X AMPLE
If y ou hav e a st y le called "Head ing 2" in y ou r Word d ocu ment s, y ou might
want new t op ics t o be creat ed whenev er Flare find s a Head ing 2 st y le in a d ocument . So y ou wou ld d ou ble-click Head ing 2 and mov e it t o t he right sid e of
t he p age.
10. Click Next.
11. (Optional) If you want Flare to split long topics into smaller ones (based on the number of
characters in a topic) or re-import updated source documents automatically, use the fields on
this page. You can also set the format of the links that connect the topics that are split.
- 34 -
n
Add "Topic Continued" links when appropriate Select this option if you want a
link called "Topic Continued" to be placed at the bottom of pages when a long topic
has been split into multiple topics.
n
Add "Topic Continued From" links when appropriate Select this option if you
want a link called "Topic Continued From" to be placed at the top of continued pages
when a long topic has been split into multiple ones.
n
Cross-Reference Format Use this field to specify the format for the "Topic Continued" and "Topic Continued From" links. Flare provides a cross-reference format for
you—(continued in {title}) or (continued from {title}). With this cross-reference format,
the link contains the words "continued in" or "continued from" within parentheses, followed by the text of the first paragraph in the connected topic. If you do not want the
link to use that particular text, you have a couple of options. First, in Flare, you could
manually enter a heading in each topic that is connected to another topic included in
the split. That text will be used in the link instead (after you update the cross- references in Flare). Another option is to modify the format by clicking the Edit button.
For more information see "Cross-References" on page 200.
n
Edit If you want to modify the cross-reference format provided, click this button,
which opens the Cross-Reference Format dialog.
n
Split Long Topics Select this option if you have long sections in your source documents and want to make sure that they are converted to multiple topics (rather than
one very long topic).
n
Threshold Enter the maximum number of characters to be converted to a topic before
a new topic is created. Flare will break the topic at the nearest paragraph to the threshold value. That way, a new topic will not start in the middle of a sentence or word, but
at the beginning of a paragraph.
n
Avoid Creating 'Empty' Topics Select this option if you want to ensure that new
topics are not created when large sections are found in the Word documents without
any content.
n
Threshold Enter the maximum number of empty character spaces allowed in a topic.
If this number is exceeded, Flare will not create a new topic from that empty space.
n
Auto-reimport before 'Generate Output' This is also known as "Easy Sync." If
you created a connection between your Word source files and the Flare project earlier in
the wizard, you will likely make future content changes in the source files. When you
make such changes, the source files need to be re-imported into the project so that they
can be included in the output. You have the option of re-importing the files manually.
However, you can also tell Flare to do this for you automatically, so that you do not
have to. Select this option if you want Flare to automatically re-import Word files
when you attempt to build output.
n
Approximate Filename Length Enter the maximum number of characters to use
for naming new topic files that are automatically created after splitting a long topic.
The default is 24.
n
Convert all tables to "Auto-Fit to Contents" Select this option if you want to
automatically set tables to "Auto-Fit to Contents" when they are imported into Flare.
This simply ensures that column widths are not specified on the imported tables.
12. Click Next.
- 35 -
MADCAP FLARE
13. (Optional) Use this page to specify whether the imported topics should be associated with a
style sheet and/or styles from your Word files.
n
Stylesheet If you already have a cascading style sheet (CSS) file that you want to associate with the imported files, click the Stylesheet button. Then navigate to the style
sheet and select it.
n
Preserve MS Word Styles This retains any styles from your Word documents so
that you can continue to use them in your new project.
n
Don't Preserve MS Word Styles This does not keep the styles that were used in
the Word documents.
n
Convert inline formatting to CSS styles This creates new styles based on any
local formatting that exists in the Word documents.
E X AMPLE
If y ou hav e ap p lied bold and it alic format t ing t o some t ext (wit hout
u sing a st y le), Flare will creat e a new st y le based on t hat format t ing.
14. Click Next.
15. (Optional) Use this page to map paragraph styles from the Word documents to Flare's paragraph styles, including those from the style sheet you may have selected. Your Word style
will adopt the name of that style (e.g., if you map a style called "MyHeading" to <h1> style
tag, the resulting style in the Flare project will be named "h1.MyHeading"). To map a style,
click the style in the MS Word column on the left, click a style in the Flare Styles section
on the far right, and then click the Map button.
The style is added to the Flare Style column. When you are finished importing the documents
and the new Flare project is loaded, the content that had been associated with the style in the
Word document will now be associated with a new style that you mapped it to.
What happens if you do not map a style? In the case of paragraph styles, they are automatically added as style classes under the <p> tag. For example, let's say you import a style
called "MyHeading" from your source document and do not map it to anything. In that case,
it will be called "p.MyHeading" in the resulting project.
16. Click Next.
17. (Optional) Use this page to map character styles from the source documents to Flare's character styles, including those from the style sheet you may have selected. In this way, you can
have your Word style take on the appearance of the Flare style that you map it to, and it will
adopt the name of that style. To map a style, click the style in the MS Word Style column,
click a style in the Flare Styles section, and then click the Map button.
Word document will now be associated with a new style that has the appearance of the style
that you mapped it to.
- 36 -
E X AMPLE
Let 's say y ou hav e a st y le in y ou r Word sou rce d ocu ment s called "Emp hasisBlu e" t hat d isp lay s t he font in blu e. Du ring t he p rocess of imp ort ing y ou r
Word d ocu ment s, let 's say y ou map t he Emp hasisBlu e st y le t o t he it alic < i>
charact er t ag. Aft er t he imp ort is finished , a new st y le called "i. Emp hasisBlue"
is creat ed and ap p lied t o all cont ent t hat had been associat ed wit h t he Emp hasisBlu e st y le in t he sou rce d ocu ment s. The cont ent now d isp lay s in a blue,
it alic font in Flare.
What happens if you do not map a style? In the case of character styles, they are automatically added as style classes under the <span> tag. For example, if you import a style
called "EmphasisBlue" from your source document and do not map it to anything, it will be
called "span.EmphasisBlue" in the resulting project.
18. Click Finish.
The Accept Imported Documents dialog opens. The files that will be created as a result of the
import are listed on the left. A preview of each file can be seen to the right when you click the
file.
19. When you are finished previewing the files to be created, click Accept.
The new project is loaded. Flare creates an XML-based file with an .flimp extension and stores
it in the Project\Imports subfolder in the Project Organizer. This file contains all the information that you provided in the wizard. If you later decide you want to make any adjustments and re-import the Word documents, you can open this file to do so.
Note: Flare supports Microsoft Word 2003 and newer versions.
- 37 -
MADCAP FLARE
Creating A Project By Importing FrameMaker Documents
Following are the steps for creating a project by importing FrameMaker documents.
Note: Before diving in to the import process, it is recommended that you first download and
review the Transition from FrameMaker Guide. This guide provides tips for making sure the
FrameMaker import process goes as smoothly as possible.
madcapsoftware.com/documentation/FlareV7/FlareTransitionFMGuide.pdf
How to create a project by importing FrameMaker documents
1. Select File>Import Project>FrameMaker Documents.
The Import FrameMaker Wizard opens.
n
If you have not yet imported FrameMaker documents that you want to re-use, click
Next.
OR
n
If you have imported FrameMaker documents into the project previously, Flare has
created an FLIMPFM file containing that data and stored it in the Project/Imports
folder. If you want to re-use these same documents or settings, click Saved Import
Data. In the Open dialog, navigate to the FLIMPFM file and double-click it.
3. Click the Add Files button to find and select FrameMaker documents on your computer to
include in the import. You can select BOOK, FM, or MIF files.
Tip: When possible, it is recommended that you select a Adobe FrameMaker BOOK file for
import and let Flare locate and import all the associated document files within the Adobe
FrameMaker book.
n
Open File This opens the FrameMaker document that is selected in the list.
n
Link Generated Files To Source Files This creates a connection between the original FrameMaker documents and the files that are created as a result of the import.
This is useful if you want to continue editing the content in the original FrameMaker
documents, instead of editing in the Flare project. Flare recognizes when changes have
been made to the source documents and reminds you to re-import the documents to
ensure the Flare project also reflects the changes.
- 38 -
n
n
n
5. Click Next. The FrameMaker documents are scanned and the next page of the wizard opens.
you import the FrameMaker documents.
8. Click Next. The paragraph styles used in the FrameMaker documents are shown on the left
side of the wizard page ("Used FrameMaker Styles").
Note: You can skip the rest of the wizard pages by clicking Finish.
9. (Optional) If you want Flare to split the FrameMaker documents into smaller topics based on
any of the styles shown on the left side of the page ("Used FrameMaker Styles"), double-click
that style to move it to the right side of the page ("New Topic Styles").
E X AMPLE
If y ou hav e a st y le called "Head ing 2" in y ou r FrameMaker d ocu ment s, y ou
might want new t op ics t o be creat ed whenev er Flare find s a Head ing 2 st y le in
a d ocu ment . So y ou wou ld d ou ble- click Head ing 2 and mov e it t o t he right
sid e of t he p age.
10. Click Next.
11. (Optional) If you want Flare to split long topics into smaller ones (based on the number of
characters in a topic) or re-import updated source documents automatically, use the fields on
this page. You can also set the format of the links that connect the topics that are split.
n
Add "Topic Continued" links when appropriate Select this option if you want a
link called "Topic Continued" to be placed at the bottom of pages when a long topic
has been split into multiple topics.
n
Add "Topic Continued From" links when appropriate Select this option if you
want a link called "Topic Continued From" to be placed at the top of continued pages
when a long topic has been split into multiple ones.
n
Cross-Reference Format Use this field to specify the format for the "Topic Continued" and "Topic Continued From" links. Flare provides a cross-reference format for
- 39 -
MADCAP FLARE
you—(continued in {title}) or (continued from {title}). With this cross-reference format,
the link contains the words "continued in" or "continued from" within parentheses, followed by the text of the first paragraph in the connected topic. If you do not want the
link to use that particular text, you have a couple of options. First, in Flare, you could
manually enter a heading in each topic that is connected to another topic included in
the split. That text will be used in the link instead (after you update the cross- references in Flare). Another option is to modify the format by clicking the Edit button.
For more information see "Cross-References" on page 200.
n
Edit If you want to modify the cross-reference format provided, click this button,
which opens the Cross-Reference Format dialog.
n
Split Long Topics Select this option if you have long sections in your source documents and want to make sure that they are converted to multiple topics (rather than
one very long topic).
n
Threshold Enter the maximum number of characters to be converted to a topic before
a new topic is created. Flare will break the topic at the nearest paragraph to the threshold value. That way, a new topic will not start in the middle of a sentence or word, but
at the beginning of a paragraph.
n
Avoid Creating 'Empty' Topics Select this option if you want to ensure that new
topics are not created when large sections are found in the FrameMaker documents
without any content.
n
Threshold Enter the maximum number of empty character spaces allowed in a topic.
If this number is exceeded, Flare will not create a new topic from that empty space.
n
Generate Images for Anchored Frames when needed This option has to do
with anchored frames in your FrameMaker documents that contain content other than
images (e.g., text callouts).
n
n
- 40 -
l
Option selected If the anchored frame contains an image along with callout
text, a new flattened image will be created as a result.
l
Option NOT selected If the anchored frame contains an image along with callout text, the original image is imported WITHOUT the callout text. You might
select this option if you have resized the image in FrameMaker. With this
option, the imported image is likely to be of a higher quality than it would be
otherwise. You can then add a callout to the image once it is inside Flare (e.g.,
by using MadCap Capture or another tool).
Preserve Image Size This option affects how the size of imported images are handled:
l
Option selected The original image is imported. However, the <img> tag is
modified in the imported file to closely reflect the height and width of the image
in the FrameMaker document. This is done regardless of whether you are importing linked or embedded images from FrameMaker documents.
l
Option NOT selected The <img> tag is not modified in the imported file.
Instead, the image is referenced at 100% of its original value.
you created a connection between your FrameMaker source files and the Flare project
earlier in the wizard, you will likely make future content changes in the source files.
When you make such changes, the source files need to be re-imported into the project
so that they can be included in the output. You have the option of re-importing the
files manually. However, you can also tell Flare to do this for you automatically, so
that you do not have to. Select this option if you want Flare to automatically re-import
FrameMaker files when you attempt to build output.
n
Approximate Filename Length Enter the maximum number of characters to use
for naming new topic files that are automatically created after splitting a long topic.
The default is 24.
n
Enable 'Passthrough' Markers Select this check box to include a check mark if you
have created passthrough markers in your FrameMaker source documents.
A passthrough marker is a special marker that you can insert into your FrameMaker
source content when you have information or code that you plan to import to Flare
and want left alone (or "passed through," leaving it exactly as you have authored it,
rather than processing it).
You can specify how the marker content should be treated when the FrameMaker document is imported. The first option is that you can import the marker content as regular text (which is the default setting). The second option is that you can import the
marker content as an XML fragment (e.g., the first part of a bold tag—<b>—but not the
second part). The third option is that you can import the marker content as a complete
XML tag.
You might use a passthrough marker for various reasons, such as for importing a
marker as XHTML or JavaScript code.
- 41 -
MADCAP FLARE
E X AMPLE
Let 's say y ou p lan t o imp ort some FrameMaker d ocu ment s t o Flare and
y ou hav e locat ions in t hose d ocu ment s where y ou want t o link t o C HM
files. The p roblem is t hat FrameMaker d oes not allow y ou t o creat e links
t o C HM files in su ch a way t hat t hose links can t hen be imp ort ed int o
anot her soft ware ap p licat ion.
Therefore, y ou creat e a p asst hrou gh marker in t he FrameMaker d ocu ment , p rov id ing t he beginning "href" t ag and p at h t o t he C HM file. Like
t his:
Then y ou creat e a second p asst hrou gh marker, p rov id ing t he end t ag for
t he link. Like t his:
When y ou imp ort t he FrameMaker d ocu ment (s), y ou can sp ecify t hat t he
p asst hrou gh markers shou ld be imp ort ed as XML fragment s. In Flare,
t he link t o t he C HM file will look and work as it shou ld .
- 42 -
n
n
Passthrough Marker Format After you enable passthrough markers, click the down
arrow in this field and select the type of format that you want to use for the import:
n
text The marker content will be imported as regular text (default setting).
n
fragment The marker content is imported as an XML fragment (e.g., the first
part of a bold tag—<b>—but not the second part). If you select this option, you
will probably need a second marker in the FrameMaker document to complete
the XML tag.
n
xml The marker content is imported as a complete XML tag.
Convert Table Styles If you have tables in your FrameMaker documents that you
have formatted in a certain way, select this check box if you want to create matching
table styles as a result of the import. In the Flare project, the new table styles will be
named after the format named applied to the table in FrameMaker (e.g., "Format_
A.css," "Format_ B.css," and so on). You can rename these table style sheets in Flare
after the import finishes.
Even if you do not use this mapping feature, the table formatting still comes across
when you import the documents. The only difference is that table style sheets make it
easier to maintain the formatting of your tables within Flare.
- 43 -
MADCAP FLARE
n
Convert Table Styles If you have tables in your FrameMaker documents that you
have formatted in a certain way, select this check box if you want to create matching
table styles as a result of the import. In the Flare project, the new table styles will be
named after the format named applied to the table in FrameMaker (e.g., "Format_
A.css," "Format_ B.css," and so on). You can rename these table style sheets in Flare
after the import finishes.
Even if you do not use this mapping feature, the table formatting still comes across
when you import the documents. The only difference is that table style sheets make it
easier to maintain the formatting of your tables within Flare.
12. Click Next.
style sheet and/or styles from your FrameMaker files.
- 44 -
n
n
Preserve FrameMaker Styles This retains any styles from your FrameMaker documents so that you can continue to use them in your new project.
n
Don't Preserve FrameMaker Styles This does not keep the styles that were used
in the FrameMaker documents.
n
Conversion Styles This opens the Import Styles Editor, which lets you specify how
to convert each property of the FrameMaker styles. If you do not enter a property
value, the value from the FrameMaker document is used. If you enter a property value,
it overrides the value from the FrameMaker document. This button is used only if you
have selected "Preserve FrameMaker Styles."
E X AMPLE
You might u se t his bu t t on, for examp le, if y ou need t o change a cross-reference format coming from FrameMaker int o somet hing more meaningful
in Flare. There are some cross- reference bu ild ing blocks in FrameMaker
t hat d o not hav e an equ iv alent in Flare. In cases su ch as t hese, t he format s are p reserv ed aft er conv ersion t o Flare. Howev er, t he format s may
t herefore ap p ear t o be broken, bu t t hey are p reserv ed t o let y ou know
t hat t here was some format t ing in a cross-reference st y le t hat Flare d id
not u nd erst and ; y ou can t hen make changes t o t he cross- reference st y le
in t he st y le sheet . Therefore, if y ou alread y know ahead of t ime t hat y ou
hav e a cross- reference st y le t hat will need t o be mod ified for u se in
Flare, y ou can u se t he C onv ersion St y les bu t t on and change t he cross-reference format t o somet hing t hat Flare u nd erst and s.
14. Click Next.
15. (Optional) Use this page to map paragraph styles from the FrameMaker documents to Flare's
paragraph styles, including those from the style sheet you may have selected. Your FrameMaker style will adopt the name of that style (e.g., if you map a style called "MyHeading" to
<h1> style tag, the resulting style in the Flare project will be named "h1.MyHeading"). To
map a style, click the style in the FrameMaker column on the left, click a style in the
Flare Styles section on the far right, and then click the Map button.
FrameMaker document will now be associated with a new style that you mapped it to.
What happens if you do not map a style? In the case of paragraph styles, they are automatically added as style classes under the <p> tag. For example, let's say you import a style
called "MyHeading" from your source document and do not map it to anything. In that case,
it will be called "p.MyHeading" in the resulting project.
16. Click Next.
- 45 -
MADCAP FLARE
17. (Optional) Use this page to map character styles from the source documents to Flare's character styles, including those from the style sheet you may have selected. In this way, you can
have your FrameMaker style take on the appearance of the Flare style that you map it to, and
it will adopt the name of that style. To map a style, click the style in the FrameMaker
Style column, click a style in the Flare Styles section, and then click the Map button.
FrameMaker document will now be associated with a new style that has the appearance of the
style that you mapped it to.
E X AMPLE
Let 's say y ou hav e a st y le in y ou r FrameMaker sou rce d ocu ment s called
"Emp hasisBlu e" t hat d isp lay s t he font in blu e. Du ring t he p rocess of imp ort ing y ou r FrameMaker d ocu ment s, let 's say y ou map t he Emp hasisBlu e st y le t o
t he it alic < i> charact er t ag. Aft er t he imp ort is finished , a new st y le called
"i. Emp hasisBlu e" is creat ed and ap p lied t o all cont ent t hat had been associat ed wit h t he Emp hasisBlu e st y le in t he sou rce d ocu ment s. The cont ent now
d isp lay s in a blu e, it alic font in Flare.
What happens if you do not map a style? In the case of character styles, they are automatically added as style classes under the <span> tag. For example, if you import a style
called "EmphasisBlue" from your source document and do not map it to anything, it will be
called "span.EmphasisBlue" in the resulting project.
18. Click Next.
19. (Optional) Use this page to map cross-reference (x-ref) styles from the FrameMaker documents to Flare's cross-reference styles, including those from the style sheet you may have
selected. In this way, you can have your FrameMaker style take on the appearance of the
Flare style that you map it to. To map a style, click the style in the FrameMaker Style column on the left, click a style in the Flare Styles section on the far right, and then click the
Map button.
and the new Flare project is loaded, the content that had been associated with the FrameMaker style in the FrameMaker document will now be associated with a new style that has
the appearance of the style that you mapped it to.
What happens if you do not map a style? In the case of cross-reference styles, they are automatically added as style classes under the <MadCap|xref> tag. For example, let's say you
import a style called "PageOnly" from your source document and do not map it to anything.
In that case, it will be called "MadCap|xref.PageOnly" in the resulting project.
- 46 -
20. Click Finish.
file.
The new project is loaded. Flare creates a file with an .flimpfm extension and stores it in the
Project\Imports subfolder in the Project Organizer. This file contains all the information that
you provided in the wizard. If you later decide you want to make any adjustments and reimport the FrameMaker documents, you can open this file to do so.
Note: Flare supports FrameMaker 7.0 and newer versions.
- 47 -
MADCAP FLARE
Creating A Project By Importing DITA File Content
Following are the steps for creating a project by importing DITA file content.
How to create a project by importing DITA file content
1. Select File>Import Project>DITA Document Set.
The Import DITA Wizard opens.
n
If you have not yet imported DITA file content that you want to re-use, click Next.
OR
n
If you have imported DITA file content into the project previously, Flare has created an
FLIMPDITA file containing that data and stored it in the Project/Imports folder. If you
want to re-use these same files or settings, click Saved Import Data. In the Open
dialog, navigate to the FLIMPDITA file and double-click it.
3. Click the Add Files button to find and select DITA files on your computer to include in the
import. You can select DITA or DITAMAP files.
Note: You cannot select multiple DITAMAP files from different folders during the same
import process. You must first import the DITAMAP file(s) from one folder; then create
another import file (Project>Import File>Add DITA Import File) and import the
DITAMAP file(s) from a second folder.
you import the DITA file content.
6. Click Next.
- 48 -
n
Open File This opens the DITA file that is selected in the list.
n
Link Generated Files To Source Files This creates a connection between the original DITA files and the files that are created as a result of the import. This is useful if
you want to continue editing the content in the original DITA files, instead of editing
in the Flare project. Flare recognizes when changes have been made to the source documents and reminds you to re-import the documents to ensure the Flare project also
reflects the changes.
n
n
n
8. Click Next.
The DITA files are scanned and the next page of the wizard opens.
9. Select any of the following options:
n
Import all Content files to one folder Select this option if you want all of the
imported DITA file content to be placed in just one folder in the Content Explorer.
n
you created a connection between your DITA source files and the Flare project earlier in
the wizard, you will likely make future content changes in the source files. When you
make such changes, the source files need to be re-imported into the project so that they
can be included in the output. You have the option of re-importing the files manually.
However, you can also tell Flare to do this for you automatically, so that you do not
have to. Select this option if you want Flare to automatically re-import DITA files when
you attempt to build output.
n
Preserve ID attributes for elements Every element inside a DITA file has an ID.
This ID is not needed in Flare. However, if you intend to send your output back out to
DITA at any point, you can select this option to make sure the ID is preserved.
10. Click Next.
- 49 -
MADCAP FLARE
style sheet and/or styles from your DITA files.
n
Conversion Styles This opens the DITA Import Styles Editor, which lets you specify
how to convert each property of the DITA elements. If you do not enter a property
value, the value from the DITA file is used. If you enter a property value, it overrides
the value from the DITA file. You can also use the dialog to import and export styles.
Note: When you import content from DITA files, there is a one-to-one conversion
that occurs. For each DITA element in your file, a style class is created in Flare as a
result. For example, let's say you have a paragraph-level DITA element called "topictitle," after you import the file, a style class called "h1.topictitle" might be created
as a result in Flare. Or if you have a character-level DITA element called
"cmdname," after you import the file, a style class called "span.cmdname" might be
created as a result in Flare. If necessary, you can later edit those style classes in
Flare. If you generate DITA output from your project, the style classes are converted back to DITA elements.
n
12. Click Finish.
file.
The new project is loaded. Flare creates an XML-based file with an .flimpdita extension and
stores it in the Project\Imports subfolder in the Project Organizer. This file contains all the
information that you provided in the wizard. If you later decide you want to make any adjustments and re-import the DITA file content, you can open this file to do so.
- 50 -
Importing A Project From Source Control
Following are the steps for importing a project from source control.
How to import a project from source control
1. Select File>Import Project>From Source Control. The Import Project From Source Control Wizard opens.
2. Follow one of these sets of steps, depending on the source control application being used:
If using Visual SourceSafe:
a. From the drop-down, select Microsoft Visual SourceSafe.
b. Next to the Database field, click Browse.
c. Find the appropriate SourceSafe database and double-click the INI file.
If using Team Foundation Server:
a. From the drop-down, select Microsoft Team Foundation Server.
b. In the Server field, enter the name of the computer or the IP address of the server.
You can also click Browse to select a "Team Project Collection." If you click this button, the Select Team Foundation Server Project Collection dialog opens, and you can do
the following:
i. To add a server, click
. The Add Team Foundation Server dialog opens.
ii. Enter the name or URL of the server.
iii. Enter the path and port number.
iv. Select the protocol (HTTP or HTTPS).
Note: You may need to obtain this information from your system administrator.
v. Click OK in the dialogs until you return to the main wizard page.
c. Next to the Team Project field, click Browse . If the Log In dialog opens, complete
the User name and Password fields.
d. Click on the Team Foundation project.
e. Click OK.
If using Subversion:
a. From the drop-down, select Subversion.
b. In the Server field, enter the name of the computer or server IP address.
- 51 -
MADCAP FLARE
If using another source control application:
a. From the drop-down, select Third Party Plug-in.
b. In the Provider field, select the appropriate source control program from the list.
c. (Optional) You might be able to click the Advanced button to enter more options.
This depends on whether the provider has enabled advanced options; if not, the button
is disabled. The advanced options available to you are different for each provider.
3. Click Next.
4. Next to the Project file field, click Browse.
5. Find and click on the Flare project file (FLPRJ) that you want to import.
6. Click OK.
7. Click Next.
8. In the Project name field, the name of the project being imported is displayed. It is recommended that you leave the name as it is, especially if you are working with other authors
on the project. However, you can enter a different project name if you want.
10. Click Finish. The project is imported and loaded into Flare.
- 52 -
Opening A Project
There are multiple ways to open an existing project.
How to open a project using the Start Page
n
On the Start Page the area labeled Open an Existing Project lists the most recently
opened projects. Click the file you want to open.
If you do not see the Start Page, click
or select View>Start Page.
How to open a project using a keyboard shortcut
1. Press CTRL+O on your keyboard.
The Open dialog displays. The Flare project file extension (.flprj) appears in the File Type
field.
2. In the Open dialog navigate to the project you want, select it, and click Open.
How to open a project using the File menu
1. Select File>Open.
field.
Note: From the File menu you can also open an existing file by clicking Recent
Projects and making your selection.
How to open a project using the Standard toolbar
1. In the Standard toolbar click
.
field.
How to open a project by dragging a file from Windows
1. Open Windows and navigate to a folder containing a Flare project file.
2. Launch Flare.
3. Drag the Flare project file from Windows to the application window and drop it on the title
bar in Flare.
Note: You can also use this method to open any file type that is supported in Flare.
- 53 -
MADCAP FLARE
Global Project Linking—Importing Files From Other Projects
You can import content and project files contained in another Flare project, thus allowing you to
maintain the information in one location but reuse it in any other project. When you use this feature
to import files, you can include or exclude particular types of files (e.g., topics, snippets, style
sheets, glossaries, targets), specific individual files, or files that have certain condition tags applied.
Simply use the include/exclude methods that work best for you. For more details about the way
Global Project Linking works when different settings are in effect, see the online Help.
This is different than a simple import process, because in this case, the imported files remain linked
to the source project. This allows you to make future updates to those files in just one place—in the
source project file. When you perform ongoing imports using your previous settings, Flare recognizes
changes to the source files. Therefore, the new files can be brought over, replacing the outdated files.
E X AMPLE
Let 's say y ou are working on t hree d ifferent Flare p roject s. Wit hin t hose p roject s,
y ou might hav e 35 t op ics and 50 images t hat are id ent ical in t he t hree p roject s. In
ad d it ion, y ou might u se t he same st y le sheet in each p roject . Rat her t han maint aining t hree d ifferent set s of id ent ical files, y ou can st ore one set of t hose files and
imp ort t hem int o t he ind iv id u al p roject s when need ed . Here are a cou p le of op t ions:
(1) One op t ion is t hat y ou cou ld consid er one of y ou r t hree Flare p roject s as t he
"global p arent " for t hose shared files. (2) Anot her op t ion is t hat y ou cou ld creat e a
new Flare p roject (p erhap s naming it "global"); t his p roject cou ld hav e no ot her p urp ose t han t o serv e as a rep osit ory for t he shared files across y ou r p roject s. In ot her
word s, y ou wou ld not necessarily generat e any ou t p u t from t his p arent p roject , but
simp ly u se it as a p lace t o hold y ou r shared informat ion.
When y ou want t o u se any of t he shared t op ic, image, or st y le sheet files from t he
global p roject , y ou wou ld imp ort t hem int o t he child p roject . This creat es a link
bet ween t he imp ort ed files and t hose in t he global p roject . Therefore, when y ou ed it
t hose files in t he fu t u re, y ou wou ld d o so from t he global p roject and t hen re-imp ort
t he changes (eit her manu ally or au t omat ically ) t o t he ot her child p roject s.
- 54 -
How to import files from another project
1. Add a Flare import file (Project>Import File>Add Flare Project Import File).
Note: After you create this file, it will be stored in the Imports folder in the Project Organizer. If you want to manually re-import files from the project in the future, you can open
this file (with an .flimpfl extension). Your settings are saved in the file, and you can
simply initiate a re-import.
2. In the Project Import Editor select the Source Project tab.
3. Under the Source Project field click Browse.
4. In the dialog find and double-click the Flare project file (.flprj extension) from which you will
be importing files.
5. (Optional) If you want future changes to the files in the source project to be re-imported automatically, click the Auto-reimport before "Generate Output" check box. If you select
this "Easy Sync" option, the changes to the source files will be re-imported automatically
when you generate output. If you do not select this option, you can re-import future changes
from the other project manually.
6. Use the Include Files and Exclude Files fields to select the type of files to be included in
the import or excluded from it. Click the down arrow next to the appropriate field and select
the type of files. Completing the Include Files field is mandatory. Completing the Exclude
Files field is optional.
If you want to import all of the files from the global project, select All Files (*.*).
Note: You are not limited to importing all files of a single file type. The following steps
explain how to add more than one file type to the field, as well as how to select specific
files to be imported while excluding others.
7. (Optional) If you want to add more file types to one of the fields, click the Edit button under
the appropriate field and use the following steps:
a. In the Import File Filter dialog click Add. The Import File Filter Designer dialog opens.
b. Select the file type that you want to add. You can also use standard wildcards (text
between asterisks) to enter patterns directly into the Pattern field (or into the Include
Files or Exclude Files fields).
- 55 -
MADCAP FLARE
E X AMPLE
Let 's say y ou want t o imp ort only t op ic files t hat cont ain t he word "Int erface" in t he file name. Rat her t han select ing t o imp ort all t op ic files and
t hen lat er sy st emat ically d eselect ing t he ones y ou d o not really want in
t he imp ort (v ia t he Accep t Imp ort ed Docu ment s d ialog), y ou can ent er
t he following:
*Interface*.htm;*Interface*.html
Or may be y ou want t o imp ort only files t hat hav e an ext ension st art ing
wit h "fl, " su ch as TOC files (. flt oc) and snip p et files (. flsnp ). In ord er t o
d o t his, y ou cou ld ent er *. fl* in t he field , like t he following:
*.fl*
c. Click OK.
d. In the Import File Filter dialog, click OK.
8. (Optional) Let's say that the files you are importing contain links to other files. If you want
Flare to automatically import those files as well, click Auto-include linked files. Not only
will the immediate linked files be included, but any linked files from those files as well, and
so on. It is a "domino" effect until no more linked files are found.
9. (Optional) In addition to specifying certain files or file types to include or exclude from the
import, you can go a level deeper through the use of condition tags. If you have applied condition tags to files in your project, you can use the Import Conditions field to tell Flare to
include or exclude certain files, depending on the condition tags that are applied to them at
the file level. Simply click the Edit button to choose the conditions. For more information
about condition tags, see "Creating Condition Tags" on page 439 and "Applying Condition
Tags to Content" on page 441.
10. (Optional) If you use the "Import Conditions" option, you may want to make sure that files
without condition tags in the source project are not included in the import. If that is the case,
click Auto-Exclude Non-Tagged Files.
11. Press CTRL+S or click
to save your work.
12. In the local toolbar of the Project Import Editor, click Import. The Accept Imported Documents dialog opens. The files in the source project are listed (depending on whether the file
types were included or excluded from the import in the previous steps).
13. (Optional) The Accept Imported Documents dialog provides you with one last look at the files
to be imported, allowing you to make sure everything is correct and letting you change your
mind on any of the files. If you recognize files in the dialog that should not be imported, you
can click the check boxes next to the files you want to exclude (removing the check marks).
You can use the Select All and Clear All buttons as necessary. For example, if you only want
to include a very small number of the files listed, you can click the Clear All button and
then manually click the check boxes next to the files you want to include (this is quicker than
individually deselecting each file that you want to exclude).
- 56 -
Note: If the current project already contains a file with the same name, the Status cell
may be highlighted in green or red. Green shading indicates that the source file is newer.
Red shading indicates that the local (or current) file is newer. If the file is identical in
both projects, the check box is deselected by default.
Tip: You might find it useful to click on the column headings in the Accept Imported Documents dialog. Doing this reorganizes the contents in alphabetical order of the column
that you click. For example, by clicking the Status column, you can easily group together
all of the files that have red or green backgrounds (i.e., files that are newer in the local
project or newer in the source project). This can be especially useful when re-importing
project files.
14. Click Accept. If the current project already contains files with the same names, you may be
asked if you want to replace the local copies. Select Yes if you do.
Warning: If you import a file and then delete, rename, or move that file in the source project,
the same change is not automatically made in the child project. You must delete the file in the
child project. If the file was deleted or moved in the source project, you will then need to reimport.
Note: When you manually import files from the parent project, you will see the Accept
Imported Documents dialog (step 12 above). This dialog lets you manually check or uncheck the
files to be imported or excluded from the import. It is sort of a last chance to take a look at the
files and make changes (include or exclude) before the actual import takes place. It also
remembers whether you have checked or unchecked certain files during previous imports. However, when you use the "auto-reimport before generate output" feature (step 5 above), the import
takes place automatically, so you do not see the Accept Imported Documents dialog. This means
that all files will be imported automatically based on the criteria you provide,
regardless of whether you have previously deselected a file during a manual
import. This is one reason it is recommended you use conditions during Global Project Linking
(step 9); with conditions, you are more assured of importing the correct files during an automatic import.
For example, let's say you have four topics—TopicA, TopicB, TopicC, and TopicD—and you have
not conditionalized any of them before importing. In your project import file, you specify that all
topic files should be imported. You then click Import. The Accept Imported Documents dialog
opens, listing all four of your topics with check marks next to each one. However, you decide
that you really do not want to import TopicD, so you remove the check mark next to it. After
completing the manual import, TopicA, TopicB, and TopicC are imported, but TopicD is not.
Later, let's say you have made changes to your files and need to re-import. After you click Reimport, you again see the Accept Imported Documents dialog. Again, check marks are automatically shown next to TopicA, TopicB, and TopicC. However, Flare remembered that you
removed the check mark next to TopicD previously, so the check mark remains absent from it.
You finish the re-import and everything goes according to plan.
- 57 -
MADCAP FLARE
Now let's say that after a few manual re-imports, you decide to use the "auto-reimport" feature.
Therefore, in your import file, you click the check box next to Auto-reimport before "Generate Output" and save. When you build the output, which topics are imported? The answer is
TopicA, TopicB, TopicC, and TopicD.
In this example, one of the best ways to use the auto-reimport feature and be assured that the
correct topics are included and excluded is to use condition tags at the file level. Therefore, in
your source project, you create one condition tag (let's say you name it "YesImport") and you
apply it to TopicA, TopicB, and TopicC. Then you create a second condition tag (let's say you
name it "NoImport") and apply it to TopicD. Then in the child project, you open your import
file. You click the Edit button next to Import Conditions, and within the dialog that opens
you tell Flare to include the "YesImport" condition and exclude the "NoImport" condition. Now,
the next time you build the output, which topics are imported? The answer is TopicA, TopicB,
and TopicC.
Note: A link icon displays next to file names that are imported from and linked to another
Flare project, Microsoft Word documents, Adobe FrameMaker documents, or DITA file content.
However, if you are also using the built-in source control technology, the source control icons
have a higher precedence and will therefore be displayed instead.
Note: The Imported Files tab displays the files that were included in the most recent import
from the source project.
Note: In the Project Import Editor, the Removed Links tab displays any files that were previously imported, but the link to the source project has since been removed. For example, let's
say that you have imported several files from a source project. After awhile, you open one of
those files in the project where the files were imported. You make a few changes and attempt to
save it. Because Flare sees that a connection exists between the file and the source project, it
prompts you with some options. One of the options is to continue to save your changes and
remove the link from the source project. This means that future changes to the file need to be
made in the current project, rather than in the source project. When you remove a link to a file
in this way, that file is added to the Removed Links tab.
- 58 -
CHAPTER 4 Adding Stuff To Projects
As soon as you start a project, you can do any number of things with it. Technically, you could
build the final output immediately. However, if it is a new project, building the output right away
would not do your end users much good, since the output does not yet have any real substance. The
project needs topics, content, cross-references, navigation, and all of the other "stuff" necessary to
help your end users.
What You Can Add to a Project
61
Topics
64
Audio
78
Browse Sequences
86
Characters and Symbols
94
97
Equations
125
External Resources
127
Footnotes
138
Glossaries
141
Indexes
147
Master Pages
178
Movies
182
Navigation Links
197
Page Layouts
275
Pictures
283
QR Code
295
Rulers
299
Scripts
300
Search
302
310
- 59 -
MADCAP FLARE
- 60 -
Snippets
322
Tables
331
Tables of Contents
338
Text Boxes
346
Variables
352
What You Can Add To A Project
Following is a list of features that you can create and insert into your Flare project. Some of these features can be used in online output as well as print-based output, some are for online output only,
and some are for print output only. Creating topics is essential for any project, but otherwise you
can pick and choose which of the following to include and which to leave out. Also, it is not necessary that you add these items and features in any particular order.
n
Topics A topic is simply a chunk of information about a particular subject. Topics are the
most important part of a Flare project. Everything else is contained within topics (e.g., crossreferences, text, pictures) or points toward topics (e.g., tables of contents, indexes, browse
sequences). The very reason end users open a Help system or manual is to find information, a
little direction. They find that help within individual topics. See "Topics" on page 64.
n
Audio To enhance your online output, you can embed Windows Media files. See "Audio" on
page 78.
n
Browse sequences For online output, if you have several topics that you think end users
should read in order, you can create browse sequences. When users view the compiled online
output, they can use your browse sequences to "browse" through topics in a particular order.
See "Browse Sequences" on page 86.
n
Characters and symbols You can insert special characters or symbols (e.g., a non-breaking
space, a copyright symbol, an ellipsis, a monetary symbol) into a topic. See "Inserting Special
Characters and Symbols" on page 95.
n
Context-sensitive Help Context-sensitive Help (CSH) is a way to "tie" your existing topics
with specific dialogs or windows in a software application, or with simple Web links created
somewhere (e.g., on a website). When users open a particular dialog or window in a software
application, or click a Web link, they can quickly open a topic pertaining to it. See "ContextSensitive Help" on page 97.
n
Equations Flare supports Mathematical Markup Language (MathML), which is a way to
describe mathematical notations in XML. Recommended by the Word Wide Web Consortium
(W3C), MathML in Flare allows you to embed virtually any kind of mathematical equation in
the XML Editor. See "Equations" on page 125.
n
External resource files The External Resources window pane lets you select and maintain
groups of external files that you want to share among Flare projects. The paths of these files
are written to the registry so they will be available for all your Flare projects. External
resources can be virtually any local or network files that you have access to (e.g., images, PDF
files, Flare project files). From the External Resources window pane, you can easily bring external files into a project (i.e., a copy of the file is added to your Flare project) and keep them
synchronized with the source files through mappings. The external resources feature is ideal
for shared files that you expect to change over time (e.g., logo images, PDFs, style sheets), as
opposed to, say, a template file that is simply copied into your project and changed only in
that project. See "External Resources" on page 127.
n
Footnotes A footnote is a comment that is used to explain a specific area of the text. It is
used primarily for print-based output. Both the area in the text and the comment contain a
number or symbol that ties the two together. A footnote comment is typically placed at the
end of a page where the corresponding number or symbol is placed in the text. Otherwise, you
- 61 -
MADCAP FLARE
can place a comment later in the manual, such as at the end of a document, chapter, section,
or book; in this case, the comment is usually referred to as an endnote. See "Footnotes" on
page 138.
- 62 -
n
Glossaries A glossary is a feature that you can add to your output to help users understand
the meaning of individual terms. You can include a glossary in both online and print-based
output. See "Glossaries" on page 141.
n
Index markers You can create an index by inserting index keywords into individual topics.
The index is generated automatically in the output when you build a target. For print-based
output, you also need to create a topic with an index proxy in order to make sure the index is
included in the output. See "Indexes" on page 147.
n
Master pages A master page is an element that you can create in your project in order to
apply certain content to multiple topics. A master page is useful in online outputs, as well as
print-based outputs. However, the benefits are somewhat different for online output than they
are for print output. For example, you might use a master page in online output to apply features such as breadcrumbs, mini-TOCs, or footer text to multiple topics, or even all topics in
a target. For print-based output, a master page allows you to determine page specifications
(such as size or orientation) and to apply certain content (such as header text or page
numbers) to many topics in a manual. See "Master Pages" on page 178.
n
Movies Not only can you explain concepts and tasks to users, but you can also show them
through the use of movies. You can insert links to MadCap Mimic movies. You can also
embed Flash, Windows Media, and QuickTime movies. See "Movies" on page 182.
n
Navigation links A navigation link is a feature that points to additional information from a
specific area in a topic. The link may open information in the same topic, a different topic, or
even a file outside of the project altogether. With print- based output the link can electronically open the destination if the user is viewing the manual online, depending on the
type of output you create (e.g., XPS, PDF, XHTML, Word). In addition, cross-reference links
can be customized to refer to specific content and page numbers in the printed manual (e.g.,
See "My Topic" on page 32). In Flare, you can create links such as cross-references, text hyperlinks, text popups, topic popups, image hyperlinks, togglers, and bookmarks. See "Navigation
Links" on page 197.
n
Page layouts A page layout is an element that you can create in your project in order to
determine page specifications (e.g., size, margins) and to apply certain content (e.g., headers,
footers, page numbers) to many (or all) topics in print-based output. Page layouts allow for
easy configuration through the use of content frames, a snap-to grid, dragging and dropping,
alignment features, and more. Page layouts are similar to master pages, but are more flexible
and easier to use. The general rule of thumb is that page layouts are recommended for printbased output (when possible), and master pages continue to be the best method for automatically adding headers, footers, and breadcrumbs in multiple topics for online output .
Another difference between page layouts and master pages is that page layouts can be used
for any of the print-based outputs (Adobe PDF, XHTML, Microsoft XPS, Microsoft Word,
Adobe FrameMaker), whereas master pages can be used only for Microsoft Word and FrameMaker when creating print-based output. See "Page Layouts" on page 275.
n
Pictures You can insert a picture into a content file (e.g., topic, snippet) to help explain
something. Flare supports the following types of raster and vector image files: BMP, EMF,
EPS, EXPS, GIF, HDP, JPG, JPEG, PNG, PS, SVG, SWF, TIF, TIFF, WDP, WMF, XAML, XPS.
See "Pictures" on page 283.
n
QR codes You can insert QR codes into content files (topics, snippets, master pages, page
layout content frame) using the XML Editor. A QR code is a type of barcode that can be read
by devices such as smart phones. The data encoded in the QR Code can be text, a website
URL, an email address, contact information, or SMS (Short Message Service, which is used for
sending text messages). Basically, QR codes are a way to bridge the gap between a static print
document and searchable, more detailed online information at your fingertips. See "QR Code"
on page 295.
n
Rulers (horizontal lines) A ruler is a horizontal line (or bar) that you can insert into a
topic. You might use a ruler, for example, as a design element to separate your topic title
from the content. See "Rulers" on page 299.
n
Scripts If you are experienced with using JavaScript, VBScript, or JScript, you can insert
such scripts into your topics. If you can create a script that can be used in a website, you can
create it in Flare as well. See "Scripts" on page 300.
n
Search You can add the search feature to any of your online output targets. When users
want to find information about a specific subject, they enter key words in the Search field. A
search engine looks through every topic in your project to find the term(s) entered by the user.
When it finds the terms, it presents the user with a list of topics to open. Search results are
ranked, not listed alphabetically. See "Search" on page 302.
n
Snippets Snippets are pre-set chunks of content that you can use in your project over and
over. Snippets are used for longer pieces of content that you can format just as you would any
other content in a topic. In snippets you can also insert tables, pictures, and whatever else
can be included in a normal topic. See "Snippets" on page 322.
n
Tables A table in Flare is much like it is in any word processing program, such as Microsoft
Word, or in a printed textbook. A table is a group of intersecting columns and rows that you
can add to a topic for various purposes, such as comparing different elements. See "Tables" on
page 331.
n
Tables of contents You can create a TOC by adding books and items with links (to topics,
external files, other Help systems, movies, etc.) in a structure that you think would be useful
for the individual. End users then browse through a TOC to find information. For printbased output, you also need to create a topic with a TOC proxy in order to make sure the generated TOC is included in the output. See "Tables of Contents" on page 338.
n
Text boxes You can insert a box into a topic and add content to it. The text box is separate
from the regular text in the topic and can be positioned in a variety of places on a page (e.g.,
aligned left on the page, outside frame, center of column). You might add a text box, for example, to create an example or case study that runs alongside the main text in a topic, in order
to enhance the reader's understanding of the main text. See "Text Boxes" on page 346.
n
Variables Variables are pre-set terms that you can use in your project over and over. They
are stored in "variable sets," which can hold multiple variables. Flare provides you with an initial variable set, but you can add as many additional variable sets as you like. Variables are
used for brief, non-formatted pieces of content (such as the name of your company's product
or your company's phone number). There are different kinds of variables: (1) those you create,
(2) system variables (e.g., date and time; Chapter, Section, and Volume numbers), (3) Heading variables, and (4) Running Head variables. Some of these are especially useful for page
headers and footers in print-based output. See "Variables" on page 352.
- 63 -
MADCAP FLARE
Topics
A topic is simply a chunk of information about a particular subject. Topics are the most important
part of a Flare project. Everything else is contained within topics (e.g., cross-references, text, pictures) or points toward topics (e.g., tables of contents, indexes, browse sequences). The very reason
end users open a Help system or manual is to find information, a little direction. They find that
help within individual topics. At this moment, you are reading a topic (called "Topics") that was
created in Flare and converted to PDF output.
Separate Files For Topic-based Authoring
Each topic is a separate XHTML file with an .htm extension. This enables you to take advantage of
topic-based authoring. In other words, rather than creating a few very long documents (as you
might do when working in a program such as Adobe FrameMaker or Microsoft Word), you create
many small documents and then piece those separate files together to produce various outputs.
Individual topic files are stored in the Content Explorer, either at the root level or in custom folders
that you create.
In your Flare project folder (you specified the location for the folder on your computer when you
created the project), the topic files are stored in a subfolder called "Content."
- 64 -
Size Of Topics
How big should a topic be?
For online output, topics are like pages on a well-designed website. They should not be too long, but
should be long enough to provide useful information. There is no specific rule for determining how
long to make your topics. It is mostly a matter of common sense. When you are developing a topic,
ask yourself if it is something that you would find useful and easy to read.
If you have a topic that seems to be getting a little long, you can break the topic into smaller topics
and provide hyperlinks from one topic to another. Another solution is to use Flare's DHTML features
(drop-down text and expanding text) to collapse areas of text until end users click a hotspot to open
the hidden text. You are currently reading content contained in a drop-down hotspot.
When it comes to creating print-based output from Flare, these small topics can be strung together
in the output to form larger chapters. It is recommended that you try to use small topics when working in Flare—usually no more than a few pages in output. Although you can certainly create a very
long topic that holds all of the content for an entire chapter or manual, smaller topics allow you to
take full advantage of Flare's many powerful single-sourcing features. For example, with small topics, you can reuse them when generating many different outputs, all from the same project. You
might want to use some topics in some outputs, but not in others. With large documents, that is
very difficult, if not impossible to do. In addition, small topics are much easier to send out to others
for review.
Topic Content
After you create a topic, you can add to it almost anything you want—text, tables, formatting styles,
cross-references, pictures, multimedia, etc. It all depends on the needs of your audience. A topic can
contain simple text, or it can contain a combination of many elements. A topic does not even need
to contain much text at all; for example, you could simply use a topic to hold a Flash-based movie
or a few lines of text for the title page in print-based output . You are only limited by what you can
do with XML.
If you are not familiar with XML, that's okay. You can use the easy XML Editor interface to edit topics in Flare, working much like you would in a program such as Microsoft Word. Flare creates the
XML tags behind the scenes for you.
Getting Behind The Scenes
Although Flare provides you with a user interface to work on topics (i.e., the XML Editor), you can
get behind the scenes to see and edit the code for the topic. The easiest way to do this is to open the
topic in the Internal Text Editor in Flare. To do this, open the topic as usual, then click
in the
local toolbar of the XML Editor.
You can also open topics in other third-party tools. One way to do this is to open the topic in Flare.
Then click the Send To button
in the Standard toolbar and select another editor.
- 65 -
MADCAP FLARE
Special Topics
In addition to the regular topics that make up your chapter content, you can create special topics
with a proxy (placeholder) for displaying generated content. These special topics are especially useful for print-based output and are often used for your manual's front matter and back matter. The
most common type of generated content is a table of contents. Other kinds of output for which you
can create topics include indexes, glossaries, endnotes, lists of elements, and lists of concepts.
- 66 -
Creating Topics
Use the following steps to create a new topic.
How to create a new topic
1. Select Project>Add Topic. The Add New Topic dialog opens.
n
n
About the factory templates available:
n
NewTopic.htm This creates a regular topic with default text that you can replace.
This is the template that you will select most of the time.
n
TopicForEndnotes.htm This creates a topic with an endnotes proxy, which can be
used to generate a list of all your end notes (footnotes) when you build print-based output.
n
TopicForGlossary.htm This creates a topic with a glossary proxy, which can be used
to generate a list of all your glossary terms and definitions when you build print-based
output.
n
TopicForIndex.htm This creates a topic with an index proxy, which can be used to
generate an index when you build print-based output.
n
TopicForListOfConcepts.htm This creates a topic with a concepts proxy, which can
be used to generate a list of all your concept keywords when you build print-based output.
n
TopicForListOfElements.htm This creates a topic with a list-of proxy, which can
be used to generate a list of any kind of element you want when you build print-based
output.
- 67 -
MADCAP FLARE
n
TopicForListOfImages.htm This creates a topic with a list-of proxy, which can be
used to generate a list of all of your images when you build print-based output.
n
TopicForListOfTables.htm This creates a topic with a list-of proxy, which can be
used to generate a list of all of your tables when you build print-based output.
n
TopicForMiniTOC.htm This creates a topic with a mini-toc proxy, which can be
used to generate a small table of contents when you build online or print-based output.
n
TopicForTOC.htm This creates a topic with a toc proxy, which can be used to generate a full table of contents when you build print-based output.
3. If you want to place the topic into a subfolder that you previously created in the Content
Explorer, click the drop-down arrow in the Folder field and select the subfolder. Otherwise,
leave the selection as "(root folder)."
4. In the File Name field type a new name for the topic.
Note: Spaces are allowed in the file name. However, if you are publishing output to a
UNIX system, avoiding spaces in the file name is recommended. You can use underscores
in place of spaces.
5. (Optional) For additional settings you can click
to see more fields.
a. If you want the heading for the topic to use the same text that you provide for the file
name, leave the 1st Heading field blank. Otherwise, enter the text that you want to
use for the heading in the topic.
b. In the Title field you can give the topic a title for the file. This does not refer to the visual title (or heading) at the top of the topic. Rather, it refers to the properties title for
the topic.
If you leave this field blank, the text from the "1st Heading" field will automatically be
used for the title.
c. If you want the heading for the topic to use the default <h1> style, leave the Style
field blank. Otherwise, select a style to apply to the heading in the topic.
d. In the Stylesheet field select a style sheet to associate with the new topic. If you do
not have a style sheet in your project, this field remains blank. This field is disabled if
you have applied a master style sheet.
6. Click Add. The Copy to Project dialog opens, displaying information about the template file
that will be copied to the project.
7. Click OK. The topic is added to the Content Explorer and opens in its own page in the XML
Editor.
8. For regular topics, simply click inside the topic page and start typing text or adding any
other elements (e.g., tables, images, cross-references, multimedia) appropriate for the topic.
For topics that contain proxies, you should remove any default text so that the topic contains
only the header and the proxy (or any additional text that you want to include).
- 68 -
Importing HTML Files
You can import multiple XHTML and HTML files into your project. HTML files are automatically
converted to XHTML.
How to import HTML files
1. Create or open a project.
2. Select Project>Import HTML Files. The Import HTML Files Wizard opens
3. Click Add Files.
4. In the dialog that opens, find and select the HTML files you want to import. You can hold the
SHIFT key to select a range of files, or you can hold the CTRL key to select individual files.
When you are finished, click Open.
- 69 -
MADCAP FLARE
5. (Optional) You can use the various options on the first page of the wizard as necessary.
n
Open File This opens the HTML file that is selected in the list.
n
Preview Conversion This opens the HTML to XHTML Conversion dialog, which lets
you see how the selected file looks in HTML and how it will look after its conversion to
XHTML.
n
Create Backups of Original Files This copies the original files and places them in
the Backups pane. If necessary, you can restore the original file later.
n
6. Click Next.
7. On the next page of the wizard, select the folder in the Content Explorer where you want to
store the imported files.
n
If you want to store the files at the root level of the Content Explorer, select Import to
project content folder.
OR
n
If you want to store the files in a specific folder, select Import to folder and use the
Browse button to select the folder. When you are finished click Open.
8. When you import HTML files, any supporting resource files (e.g., style sheets, images, multimedia files) can be copied over to the project as well. If you want to include those resource
files in the import, click Import Resources and selecting one of the following:
- 70 -
n
Keep existing structure The supporting resources files will be copied into folders
with the same names and hierarchy as those used in the source.
n
To project resources folder The supporting files will be placed in the Resources
folder in your Flare project.
n
To folder The supporting files will be placed into whatever folder in your project that
you specify.
9. Click Finish.
10. After the files are imported, click Close in the Converting dialog.
- 71 -
MADCAP FLARE
Opening Topics
After you create topics, they are stored in the Content Explorer. You can open as many existing topics as you want at one time. Each topic displays in its own page of the XML Editor and remains
accessible as you work. As you open more topics or other elements (e.g., targets, tables of contents,
style sheets), each page displays in the appropriate editor (e.g., XML Editor, Target Editor, TOC
Editor, Stylesheet Editor). By default, the most recently opened page tab is on the left side of the
editor section in Flare, and the tabs for the previously opened pages shift to the right. The active
page displays on top of the other pages, and you can make any page the active one (or "the one on
top") by simply clicking its tab.
You can open topics the traditional way, from inside the interface. But you can also open them by
dragging topic files from a Windows folder.
How to open an existing topic from within the interface
1. Make sure the Content Explorer is open.
2. All of your topics are displayed under the Content folder (or under subfolders that you have
created previously when organizing your topics). Locate the file that you want to open. You
can use the "multi-view" to do this.
Shows or hides the folders that the files are stored in.
Shows or hides the files. If you click this button when the "Show Folders" button is
selected, the area splits into two halves. The folder is shown on the left side, and the
files and subfolders within it are shown on the right.
Expands the folders.
Collapses the folders.
If the "Show Files" button is the only one selected, you can click this button to move
up one folder level.
3.
Do one of the following:
n
Locate and double-click the topic that you want to open.
OR
n
Locate and click the topic you want to open. In the local toolbar, click
The topic opens in its own page of the XML Editor.
- 72 -
.
How to open an existing topic by dragging it from Windows
1. Open Windows and navigate to a folder containing a Flare project file.
2. Open the Content subfolder and locate the topic that you want to open.
3. Launch Flare.
4. Drag the topic file from Windows to the application window and drop it on the title bar in
Flare.
Note: You can also use this method to open any file type that is supported in Flare.
- 73 -
MADCAP FLARE
About Layout Modes
There are two views to choose from in the XML Editor when you edit topics and snippets—"Web Layout mode" and "Print Layout mode."
n
Web Layout mode This mode is useful for seeing how the topic will look online. It displays
your content without showing any headers or footers from a page layout.
n
Print Layout mode This mode lets you see how the pages will look with a page layout
applied to it. In other words, it lets you see how the page will look when you generate printbased output. This means that you will be able to view the actual page size and orientation,
as well as the margins and any header or footer content.
Note: Although the Print Layout mode is a WYSIWYG (What You See Is What You Get)
environment, you also need to consider any condition tags when you are viewing pages in
this mode. For example, let's say you have applied a condition tag to an entire paragraph
on a page. When you are viewing the topic in the XML Editor, you will see this paragraph, but if you generate a target where you have elected to exclude that condition tag,
the paragraph will not be displayed in the output, and the other paragraphs will shift to
compensate for its absence. Therefore, what you see in the Print Layout mode is what you
get, except possibly for certain conditions that may be present on a page.
Note: Different operating systems render text differently in the XML Editor. For example,
if you are using Microsoft Vista, the text may look a bit smaller than it does in Microsoft
XP. Therefore, if you and another author are looking at the same topic from the same
project, but you have different operating systems, the topic may look differently for you
than it does for the other person.
Note: If you set a table to a specific height, that height may not be represented accurately
if you are viewing the topic in Print Layout mode.
- 74 -
You can toggle between the two views in the XML Editor by clicking the Layout Mode button:
or
.
- 75 -
MADCAP FLARE
- 76 -
If you double-click on a topic page in Print Layout mode (outside the flow of the main body text),
the associated page layout will open in the Page Layout Editor.
As you add more and more content to the topic, pages are added below. A navigation toolbar at the
bottom of the editor lets you see how many pages are in the topic and quickly navigate to any of
them as necessary.
- 77 -
MADCAP FLARE
Audio
You can insert Windows Media audio directly into your Flare topics or snippets. See "Inserting
Audio Files" on the following page.
There are two ways to do this. First, you can use the Insert>Multimedia option. When you use
this option, the audio is embedded into the topic or snippet. In addition, you can specify advanced
settings, such as whether to include controls with the audio (e.g., Play, Pause), whether to automatically start the audio when the topic displays, and audio levels.
Second, you can use the Insert>Hyperlink option. When you use this option, the user must click
the text link in order to open the audio. Also, you can choose to play the audio in another window.
Following are the audio file types supported.
.asf
.mp4
.wax
.au
.mpa
.wm
.mid
.mpeg
.wma
.midi
.mpg
.wmx
.mp3
.wav
Note: When you insert an audio file from outside your project (using the Insert>Multimedia
option), a copy of the file is added to your project. The file is stored in the Content Explorer
(Resources\Multimedia subfolder).
MULTIMEDIA NOT WORKING? Due to issues with Windows Media, these files will not
work in the compiled output if the link from the topic to the media file has ../ at the beginning.
For example, let's say you have a topic at the root level of the Content Explorer and another
topic that is in a folder you created. Suppose that each of these topics contains a link to a Windows Media file that is stored (by default) in the Resources/Multimedia folder in the Content
Explorer. The file will work in the first topic but not in the second. The solution is to move
either the topic or the multimedia file to fix the link. Therefore, you might decide to move the
multimedia file into the folder where the topic is stored. Alternatively, you might move all topics that use multimedia into one folder. Then, you might place all multimedia files in that
same folder or a subfolder within it.
- 78 -
Inserting Audio Files
You can insert audio files directly into your Flare topics or snippets.
There are two ways to do this—embedded and linked.
n
Embedded You can use the Insert>Multimedia option. When you use this option, the
audio is embedded into the topic or snippet. In addition, you can specify advanced settings,
such as whether to include controls with the audio (e.g., Play, Pause), whether to automatically start the audio when the topic displays, and audio levels.
n
Linked You can use the Insert>Hyperlink option. When you use this option, the user
must click the text link in order to open the audio. Also, you can choose to display the audio
interface in another window.
How to insert an audio file (embedded)
1. Open the content file (e.g., topic, snippet).
2. In the XML Editor, place your cursor where you want to insert the audio.
3. Select Insert>Multimedia>Windows Media Player.
The Insert Multimedia dialog opens.
4. Select the General tab.
5. Select an audio file to insert. You can do this in various ways.
You can select an audio file already in the project by finding and choosing it in the Select File
Area. Use the buttons in the local toolbar to view all files in a list, view files in their folder
structure, etc.
Shows all of the files in the project in a list in the area below. If you click the button
again, it switches to a folder tree view. In the list, you can click the "File," "Type," or
"Path" column headers to sort the list alphabetically by that column data.
You can click
to find and select an audio file outside of the project.
If you want to select an audio file that you recently inserted somewhere in your project, click
the down arrow in the field next to
and select the file from the list.
- 79 -
MADCAP FLARE
Note: If you select an audio file outside the project, that file is then copied and placed
inside the project. The audio file is stored in the Resources\Multimedia folder of the Content Explorer.
6. (Optional) If you want to apply a specific style class to the audio, you can select it from the
Style Class field.
E X AMPLE
Let 's say t hat y ou hav e creat ed in y ou r st y le sheet a class of t he < object > t ag
called "BigMargin" (i. e. , object . BigMargin) and y ou hav e set t he margin for all
sid es of t hat class t o 1 inch. Rat her t han u sing t he d efau lt p arent < object > t ag
when y ou insert t he au d io, y ou select object . BigMargin from t he St y le C lass
d rop -d own. As a resu lt , 1 inch of sp ace is ad d ed arou nd t he au d io int erface in
t he ou t p u t .
7. (Optional) In the Screen Tip field you can type a phrase that will appear when the end user
hovers over the audio link.
8. (Optional) Select the Advanced tab and complete the options as necessary.
n
Player Controls Select an option for displaying the player controls (e.g., Play, Pause,
Volume).
l
Full Displays all of the available player controls.
l
None Does not display any player controls.
l
Mini Displays only some of the player controls (Play, Pause, Stop, Mute, Volume).
l
Invisible Hides the audio interface entirely, while still playing the audio. If you
select this option, you might want to resize the container square in your topic so
that it does not take up so much space in the output. The user will simply see
blank space where the container exists.
n
Auto start Select this option if you want the audio to automatically begin playing
when the topic displays. Otherwise, the user must click the Play button to start the
audio.
n
Full screen Select this option to display the audio interface using the entire screen.
n
Stretch to fit Select this option to automatically resize the audio interface so that it
exactly matches the size of the container area.
n
Play count Enter the number of times you want the audio to repeat.
n
Audio Select options for the sound (mute, volume level, balance).
9. (Optional) Select the Size tab and complete the options as necessary to resize the container
area where the audio interface will be displayed. As an alternative, you can click and drag the
icon
in the lower-right corner of the container.
- 80 -
To set a precise width and/or height:
n
In the Width and/or Height field of the Size section, provide the settings. First you
need to select Length in the top drop-down list. You can then enter a value in the
lower-left area and choose from several different units of measurement (points, pixels,
centimeters, etc.) in the lower-right area.
Note: When resizing objects, you can ensure that the aspect ratio is maintained.
For example, if you want certain objects to be resized so that each is exactly 3
inches high, you can make sure that the width of each object is adjusted accordingly so that it stays in proportion. To do this, you would first set the height at 3
inches. Then for the width property, you would select Automatic (instead of
"Length") from the top drop-down list. In the same way, if you were to specify an
exact width, you could maintain the aspect ratio by setting the height to "Automatic."
To set the minimum width and/or height:
If the original object is smaller than the minimum width or height that is set, it will be
enlarged so that it reaches the minimum value. If the original object is larger than the minimum width or height, it will not be resized.
n
In the Width and/or Height field of the Minimum Size section, provide the settings. First you need to select Length in the top drop-down list. You can then enter a
value in the lower-left area and choose from several different units of measurement
(points, pixels, centimeters, etc.) in the lower-right area.
For example, if you want certain objects to be resized so that they are at least 2
inches wide, you can make sure that the height of each object is adjusted accordingly so that it stays in proportion. To do this, you would set the minimum width
at 2 inches. You would then leave the minimum height property unspecified. In the
same way, if you were to specify a minimum height, you could maintain the aspect
ratio by not setting the minimum width property.
To set the maximum width and/or height:
If the original object is larger than the maximum width or height that is set, it will be reduced
in size so that it is no greater than the maximum value. If the original object is smaller than
the maximum width or height, it will not be resized.
n
In the Width and/or Height field of the Maximum Size section, provide the settings. First you need to select Length in the top drop-down list. You can then enter a
- 81 -
MADCAP FLARE
For example, if you want certain objects to be resized so that they are no more than
5 inches wide, you can make sure that the height of each object is adjusted accordingly so that it stays in proportion. To do this, you would set the maximum width
of the style at 5 inches. You would then leave the maximum height property
unspecified. In the same way, if you were to specify a maximum height, you could
maintain the aspect ratio by not setting the maximum width property.
10. (Optional) Select the Position tab and complete the options as necessary to determine how
the audio interface is positioned in the topic. You can select a Float and a Clear setting. You
can also set the Vertical Alignment of the object.
Float Use this field to specify where to place the object on the page.
n
None Does not place the object in a specific location.
n
Left Positions the object on the left side of the page frame, allowing you to type text to
the right of the object.
n
Right Positions the object on the right side of the page frame, allowing you to type
text to the left of the object.
n
Center of Column Positions the object in the center of the column on the page.
n
Outside Left Margin Positions the object beyond the left margin of the topic text.
n
Outside Right Margin Positions the object beyond the right margin of the topic
text.
n
Outside Frame Positions the object outside of the page frame.
n
Outside Frame, Top Align Positions the object outside of the page frame, as well as
aligning it with the top of the frame.
n
Left of Frame Positions the object to the left of the page frame.
n
Right of Frame Positions the object to the right of the page frame.
n
Center of Frame Positions the object both vertically and horizontally in the middle
of the page frame.
Clear Use this field to position an object so that it is "clear" of an adjacent object. For example, let's say you have already inserted an object and applied the float left property to it. If
you then insert another object immediately after the first object , you want to make sure that
the second object doesn't rest next to the first object. Instead, you want the second object to
be placed completely below the first object . Therefore, you can apply a clear property to the
second object.
- 82 -
n
None Does not apply the clear property to the object.
n
Left Side The object will be placed below the bottom outer edge of a previous object
that is floating left.
n
Right Side The object will be placed below the bottom outer edge of a previous object
that is floating right.
n
Both Sides The object will be placed below the a previous object, whether it is floating
left or right.
Vertical Alignment Use this field to adjust where the item is positioned vertically.
n
Baseline The baseline of the box will be aligned with the baseline of the parent box.
n
Text Top The top of the box will be aligned with the top of the parent element's font.
n
Text Bottom The bottom of the box will be aligned with the bottom of the line box.
n
Top The top of the box will be aligned with the top of the line box.
n
Middle The vertical midpoint of the box will be aligned with the baseline of the parent
box, plus half the x-height of the parent.
n
Bottom The bottom of the box will be aligned with the bottom of the line box.
11. (Optional) Select the Borders & Margins tab if you want to specify margins, padding, or
borders around the audio interface.
Margin: Click in any of the individual fields (Left, Right, Top, Bottom) to specify the settings for the margins around the object. If you click the down arrow to the right of all the
fields, the settings will be applied to all of the margin fields.
Padding: Click in any of the individual fields (Left, Right, Top, Bottom) to specify the settings for the padding. In the left side of the field, enter a number for the amount of padding.
In the right side of the field, select a unit of measurement (e.g., point, pixel, centimeter) for
the number you entered. If you click the down arrow to the right of all the fields, the settings
will be applied to all of the padding fields. When you click that down arrow, a small popup
displays.
Borders:
a. Click in any of the individual fields (Left, Right, Top, Bottom) to specify the settings
for the border. If you click the down arrow to the right of all the fields, the settings will
be applied to all of the border fields.
When you click that down arrow or in one of the individual fields, a small popup displays.
b. Use the lower-left area of the popup to enter a number for the border thickness.
c. Use the lower-middle area to select a unit of measurement (e.g., point, pixel, centimeter) for the number you entered.
d. Use the upper-right area to select a color for the border.
e. Use the lower-right area to select a line type (e.g., solid, double, dashed) for the border.
f. Click OK.
- 83 -
MADCAP FLARE
12. (Optional) Select the Background tab if you want to add background settings to the audio
interface. This includes the ability to specify a color, an image, and a repeating pattern for the
background image.
Set a color for the background:
n
In the Color field, click the down arrow and select a color from the popup. For
advanced color options, select More Colors and use the fields in the Color Picker
dialog.
Add an image to the background:
a. Next to the Image field, click the Browse button.
The Insert Picture dialog opens.
b. Select an image file to insert and click OK.
c. If you want the background image to repeat, select one of the options from the Repeat
field. You can also set the image position horizontally and vertically by using the X
and Y fields.
13. Click OK.
The audio is added to the topic, represented by a gray square or rectangle, which is the area
where the audio interface will be shown in the output.
- 84 -
to save your work.
How to insert an audio file (linked)
1. Add the multimedia file to the project (Project>Add Multimedia).
3. In the XML Editor, highlight the text that you want to use as the link (or "hotspot") to the
audio file.
4. Select Insert>Hyperlink or click
in the local toolbar.
5. From the Link to field select File in Project.
6. Navigate to the audio file that you want to link to and select it.
7. (Optional) The Link text field displays the text that you highlighted in the topic, which will
be used as the hyperlink. Leave the text as it is, unless you decide you would like to change
it. If you want to change the link text, type the new text in the field. It will replace the previously selected text in the topic.
8. (Optional) In the Screen Tip field, you can type a phrase that will appear when the end
user hovers over the hyperlink in the output.
9. (Optional) Next to the Style Class field, click the Select button. This opens the Select Class
dialog, which lets you apply one of the defined hyperlink styles from your style sheet to the
link. You can change the appearance of the link in the Stylesheet Editor. After you select a
style class in the dialog, click OK. The Style Class field displays the selected style. (If you do
not specify a style class, Flare uses the parent <a> tag.)
10. (Optional) In the Target Frame field, click the drop-down arrow to select the way the
linked destination will open (e.g., in another window, in a popup). For descriptions of the
options, see the online Help.
11. Click OK.
The hyperlink is added to the topic.
to save your work.
- 85 -
MADCAP FLARE
Browse Sequences
For online output, if you have several topics that you think end users should read in order, you can
create browse sequences. When users view the compiled online output, they can use your browse
sequences to "browse" through topics in a particular order.
A browse sequence XML file has an .flbrs extension and is stored in the Project Organizer under the
Advanced folder.
Steps For Using Browse Sequences
Following are the tasks necessary for creating a browse sequence and making it accessible to end
users.
1. Add/open browse sequence Add a new browse sequence to your Flare project, or open an
existing one from the Project Organizer to work on it. See "Adding a Browse Sequence File" on
the following page or "Opening a Browse Sequence" on page 88.
2. Create browse sequence In Flare, you create a browse sequence in much the same way
that you create a table of contents—by adding books and links to topics in a structure that
you think would be useful for the individual. See "Creating a Browse Sequence" on page 89.
3. Edit browse sequence entries After you create a browse sequence, you can edit the
individual entries in many ways. This includes linking entries to other files, setting titles automatically, and applying condition tags. See "Editing Browse Sequence Entries" on page 90.
4. Enable browse sequence After creating the browse sequence, you need to enable it in the
skin you want to use for the target. See "Enabling Browse Sequences in Skins" on page 92.
5. Associate skin with target Now that the browse sequence is enabled in the skin, you need
to associate that skin with the target you are building. See "Associating Skins with Targets"
on page 412.
6. (Optional) Associate master browse sequence with target If you have multiple
browse sequences that you want to include in the same output target, the browse sequence
that you associate with the target serves as the "master" browse sequence. In your master
browse sequence, you can create links to the other browse sequences that you want to include
in the output. If you do not select a browse sequence, Flare will use the first one in the project
(if there is more than one). See "Associating a Browse Sequence with a Target" on page 93.
- 86 -
Adding A Browse Sequence File
The first step in creating a browse sequence is to add a browse sequence file to your project. This file
has an .flbrs extension and is stored in the Project Organizer under the Advanced folder.
How to add a browse sequence file to a project
1. Select Project>Advanced>Add Browse Sequence.
The Add Browse Sequence dialog opens.
n
n
3. In the File Name field, type a new name for the browse sequence.
4. Click Add.
5. Click OK.
The browse sequence is added to the Advanced folder in the Project Organizer. The Browse
Sequence Editor opens to the right, with an initial browse sequence entry shown.
- 87 -
MADCAP FLARE
Opening A Browse Sequence
When you want to work on an existing browse sequence, use the following steps to open it.
How to open an existing browse sequence
1. Make sure the Project Organizer is open.
2. Double-click the Advanced folder.
The browse sequence(s) in your project are displayed.
3. Double-click the browse sequence that you want to open.
The Browse Sequence Editor opens to the right, with the browse sequence page shown.
- 88 -
Creating A Browse Sequence
You can create a browse sequence if you have several topics that you think end users should read in
order. When users view the compiled online Help system, they can use your browse sequences to
"browse" through topics in a particular order. In a browse sequence, you can create books and links
to topics, tables of contents, other browse sequences in your project, and movies.
How to create a browse sequence
1. If you do not already have one in your project, add a new browse sequence file (select
Project>Advanced>Add Browse Sequence).
2. If it isn't already displayed in the Browse Sequence Editor, open your browse sequence from
the Advanced folder in the Project Organizer.
4. (Optional) If you want to select and add multiple topics to the browse sequence at the same
time (as opposed to one topic at a time), complete these steps:
a. In the local toolbar of the Content Explorer, click the Show Files button
.
The Content Explorer splits into two halves.
b. On the right half of the Content Explorer, find and select the folder and topic files that
you want to include in the browse sequence. You can hold the SHIFT key to select a
range of files, or you can hold the CTRL key to select individual files.
Note: Make sure you do not select the "Resources" folder in the Content Explorer,
which holds your ancillary content files (e.g., images, style sheets). If you do, that
folder and its contents will also be included in the browse sequence.
5. Click and drag topic files from the Content Explorer to the Browse Sequence Editor.
Also, you can use the buttons in the Browse Sequence Editor local toolbar to add elements
(e.g., books, items) to the browse sequence and to determine how they behave (e.g., link them
to topics, tables of contents, other browse sequences, or other Help systems). For details, see
the online Help.
to save your work.
- 89 -
MADCAP FLARE
Editing Browse Sequence Entries
After you create a browse sequence, you can edit the individual entries in the following ways:
n
Auto-generate In many cases, Flare provides you with an initial browse sequence, which
you further "build" (or create) using the Browse Sequence Editor. You can easily create a
browse sequence manually, adding books, as well as links to files, in any kind of structure you
want. Another option is to auto-generate a browse sequence. For more information see the
online Help.
Note: This feature is for online output types only (DotNet Help, HTML Help, WebHelp,
WebHelp Plus, WebHelp AIR, WebHelp Mobile). It is not intended for print-based outputs (Adobe PDF, XHTML, Microsoft XPS, Microsoft Word, Adobe FrameMaker).
- 90 -
n
Auto-merge You can determine where other Flare project outputs are merged relative to
your "master" project's browse sequence if you are generating WebHelp Plus output and you
are publishing the files to a Web server running Microsoft IIS. For more information see the
online Help.
n
Browser frame You can specify the kind of browser frame that a linked file should open
when a user clicks the browse sequence entry in the output. For more information see the
online Help.
n
Condition tags You can associate condition tags with a particular browse sequence entry so
that it appears in some outputs but not in other outputs. See "Applying Condition Tags to
Content" on page 441.
n
Icon for HTML Help You can select an icon to use for a particular browse sequence entry
in HTML Help output. For more information see the online Help.
n
Label You can change the label text for a browse sequence entry. For more information see
the online Help.
n
Link to browse sequence You can link a browse sequence entry to another browse
sequence. For more information see the online Help.
n
Link to CHM file You can link a browse sequence entry to an HTML Help (CHM) file that
you have already brought into your project (perhaps via the external resources feature), or you
can select a CHM file located elsewhere, in which case a copy of it is added to your project..
That CHM file will then be merged with the current project when you build the output. For
more information see the online Help.
n
Link to external Help system You can link a browse sequence entry to the output file
from another Help project. This option is useful if you are sharing a Help system with
another author and need to retrieve it from a remote location. You can select Flare output files
(e.g., DotNet Help and WebHelp). That output file will then become linked to the browse
sequence entry and merged with the current project when you build the output. For more
n
Link to Flare project and target You can link a browse sequence entry to a target in a
Flare project. (Make sure you select a target of the same output type as the current project.)
That project and target will then become linked to the browse sequence entry and merged
with the current project when you build the output. For more information see the online
Help.
n
Link to Mimic movie You can link a browse sequence entry to a MadCap Mimic movie or
project. For more information see the online Help.
n
Link to TOC You can link a browse sequence entry to a TOC. For more information see the
online Help.
n
Link to topic If you drag topics from the Content Explorer to the Browse Sequence Editor,
the entry that is created is automatically linked to that topic. If you want to change the link,
or if you have created an entry that is not yet linked to a topic, you can easily do so
manually. For more information see the online Help.
n
Mark as new You can specify whether a browse sequence entry should be displayed as
"new" in the output. For more information see the online Help.
n
Skin You can add skins to your project to help create a look and feel for online output that
you generate. After you create a browse sequence, you can associate a browse sequence entry
with a particular skin. See "Skins" on page 405.
n
Style class For certain elements of the online output window (e.g., navigation pane, TOC or
browse sequence entries, index keywords) you can determine skin style settings. You can edit
styles in Standard skins
to make changes for WebHelp, WebHelp Plus, WebHelp AIR,
DotNet Help, and HTML Help outputs. In addition, you can edit styles in WebHelp
Mobile skins
to make changes for WebHelp Mobile output. If you are generating one of
the WebHelp output types, you can use the TocEntry style in the Styles tab of the Skin Editor
to change the look of individual entries in your browse sequence. You can also select the
TocEntry style in the Skin Editor and use the Add Class button in its local toolbar to create
classes of that style. If you do that, you can select a particular class for a browse sequence
entry so that you can give it the look you want. For more information see the online Help.
n
Title You can automatically set the name of the browse sequence entry as the title for the
topic in the output. This overrides the title that you may have provided for the topic in the
Properties dialog for that topic. For more information see the online Help.
- 91 -
MADCAP FLARE
Enabling Browse Sequences In Skins
After you create a browse sequence, you need to enable browse sequences in the skin that you intend
to use for your target.
How to enable a browse sequence in a skin
1. Open the skin from the Project Organizer. For more, see "Skins" on page 405.
2. On the General tab, click the Browse Sequences check box so that it contains a check
mark.
- 92 -
to save your work.
Associating A Browse Sequence With A Target
After you enable a browse sequence in a skin, you need to associate it with a target (unless it is
linked to another browse sequence that is associated with a target).
How to associate a browse sequence with a target
If you have created only one browse sequence for your project, you do not need to associate it with a
target. It will display automatically after you build the target. However, if you have added more
browse sequences, you need to specify which one will serve as the "master browse sequence." This is
the browse sequence that will be displayed in the output. The additional browse sequences will also
be displayed if you have linked to them from the master browse sequence. Use the following steps to
specify a master browse sequence, associating it with a target.
1. Open the target from the Project Organizer.
2. On the General tab, click the drop-down arrow in the Browse Sequence field, and select
the browse sequence that you want to associate with the target.
to save your work.
- 93 -
MADCAP FLARE
Characters And Symbols
You can easily add special characters and symbols to your content in Flare.
Specifying Quick Characters
If there is a particular character or symbol (e.g., a non-breaking space, a copyright symbol, an ellipsis, a monetary symbol) that you use in topics quite frequently, you can associate it with the Quick
Character button in the local toolbar of the XML Editor. Then, whenever you click the Quick Character button, that specific character or symbol will be inserted into the topic. This feature is also a
way to insert characters or symbols that are not included in the basic list of characters and symbols
provided by Flare.
How to specify a quick character
2. Select Insert>Character>Select 'Quick Character.'
The Quick Character dialog opens.
3. Enter the information for the character into one of the two fields in the dialog.
n
Enter the character symbol… One way to specify the character symbol to use is to
copy it from a source and paste it into this field. The field below with the Unicode will
then automatically be populated for you.
OR
n
Use the text box below to enter the Unicode… Another way to specify the character symbol to use is to enter the Unicode for it in this field. The field above with the
symbol itself will then automatically be populated for you.
Following are some Unicode resources:
o
http://www.unicode.org/charts/
o
http://unicodelookup.com/
o
http://en.wikipedia.org/wiki/Unicode_symbols
4. Click OK.
In the future, whenever you click the -a- portion of the Quick Character button
press F11 on your keyboard, that character will be inserted into the active topic.
- 94 -
or
Inserting Special Characters And Symbols
You can insert special characters or symbols (e.g., a non-breaking space, a copyright symbol, an ellipsis, a monetary symbol) into a topic. This can be done by inserting a quick character that you have
specified, or by selecting a character or symbol from the list provided.
How to insert a quick character
1. Make sure you have specified the quick character. See "Specifying Quick Characters" on the
previous page.
3. Place your cursor where you want to insert the character or symbol.
n
Click the -a- portion of the Quick Character button
.
OR
n
Select Insert>Character>Quick Character.
OR
n
Press F11.
to save your work.
How to insert a character or symbol from the list provided
2. Place your cursor where you want to insert the character or symbol.
n
Click the down arrow portion of the Quick Character button
.
OR
n
Select Insert>Character.
4. Select a character or symbol from the list.
n
Non-breaking Space Inserts a non-breaking space into the topic. This is a special
space character that prevents an automatic line break (line wrap) at its position. Also
known as a hard space or fixed space, it can be used to create multiple spaces in a row.
You can also insert a non-breaking space by pressing SHIFT+SPACE on your keyboard.
n
Copyright Inserts a copyright symbol (©) into a topic.
n
Registered Trademark Inserts a registered trademark symbol (®) into a topic.
n
Trademark Inserts a trademark symbol (™) into a topic.
n
Degree Inserts a degree symbol (°) into a topic.
n
Bullet Inserts a round black bullet (•) into a topic.
- 95 -
MADCAP FLARE
n
Double Dagger Inserts a double dagger symbol (‡) into a topic.
n
Ellipses Inserts an ellipsis (…) into a topic. This is a better method for creating an
ellipsis than typing three periods in a row. If you use this symbol, the Find and
Replace feature will not find the repeated periods and consider them a mistake.
n
N Dash Inserts an n-dash (–), or en dash, into a topic.
n
M Dash Inserts an m-dash (—), or em dash, into a topic.
n
Plus/Minus Inserts a plus/minus symbol (±) into a topic.
n
Greater or Equal Inserts a combined "greater or equal" symbol (≥) into a topic.
n
Not Equal Inserts a "not equal" symbol (≠) into a topic.
n
Cent Inserts a cent monetary symbol (¢) into a topic.
n
Euro Inserts a euro monetary symbol (€) into a topic.
n
Pound Inserts a pound monetary symbol (£) into a topic.
n
Yen Inserts a yen monetary symbol (¥) into a topic.
- 96 -
to save your work.
Context-sensitive Help (CSH) is a way to "tie" your existing topics with specific dialogs or windows
in a software application, or with simple Web links created somewhere (e.g., on a website). When
users open a particular dialog or window in a software application, or click a Web link, they can
quickly open a topic pertaining to it.
E X AMPLE
Let 's say y ou are creat ing an online Help sy st em for y ou r comp any 's soft ware ap p licat ion. This ap p licat ion cont ains a d ialog called "Prop ert ies" t hat u sers op en t o sp ecify set t ings for a p art icu lar element . In y ou r Help p roject , y ou hav e writ t en a t op ic
t o exp lain t his Prop ert ies d ialog. By creat ing C SH, u sers will be able t o op en t hat
sp ecific t op ic by clicking a Help bu t t on on t he Prop ert ies d ialog (or by p ressing F1
when it is op en).
Who Is Involved?
Creating CSH is mostly a joint effort between you and the software developer. There are tasks
that you must perform and tasks that the developer must perform in order for CSH to be implemented successfully. For this reason, it is essential that you communicate clearly with the developer
when planning, creating, and implementing CSH. Other individuals (managers, other Help authors,
etc.) may also be involved as well, particularly in the early planning stages.
However, there might be times when you function as both the author and the developer. For example, this might be the case if you are generating WebHelp output and simply want to create links on
a website that open specific parts of your output. In that situation, you might first generate the
online output with the CSH information. Then you might serve as the developer, modifying pages
on a website to include CSH links pointing to your documentation.
Planning The CSH
For CSH to be successful, some initial planning is necessary. This includes making decisions such
as:
n
Which type of output is being created (e.g., DotNet Help, WebHelp, WebHelp Mobile)?
n
Which dialogs and windows will be included in the CSH (if connecting to an application)?
n
Where will the links be located (if connecting to simple Web links)?
n
What will the Help buttons look like on the dialogs or windows?
n
Will the CSH Help topics open in a different window than the other topics in the Help system
(different size, position, and appearance)?
Depending on how your company operates, questions such as these may be decided independently
by you or the developer. Or they may be decided jointly by you, the software developer, and others
(managers, other authors).
- 97 -
MADCAP FLARE
Another major decision that needs to be made at the beginning of the process is whether you or the
developer will be responsible for providing the header file that is necessary for CSH. This decision is
typically made jointly by you and the software developer. See "Header Files" on page 100.
What Needs To Be Done And Who Does What?
Following are two sets of general guidelines containing the necessary steps for creating CSH. Each
set of guidelines is slightly different, based on whether you or the software developer provides the
header file.
C SH Steps — If You Provide The H eader File
1. You — Add a header file to the project.
See "Header Files" on page 100 and "Adding Header Files" on page 102.
Note: If you are importing FrameMaker documents and you create topic alias markers in
the source files, this file will be created automatically when you perform the import.
2. You — Add an alias file to the project.
See "Alias Files" on page 104 and "Adding Alias Files" on page 104.
3. You — Create and assign identifiers.
See "Creating and Assigning Identifiers" on page 112.
Note: If you are importing FrameMaker documents, you can create topic alias markers in
the source files as an alternative to creating identifiers in Flare. When you import the
FrameMaker files, the identifiers will be created for you in Flare.
4. You — Associate the alias file with the target.
This is necessary only if you have created more than one alias file. See "Associating an Alias
File with a Target" on page 122.
5. You — Provide the developer with a copy of the header file.
For example, you can do this by exporting the file to a shared drive. See "Providing a Developer with a Header File" on page 123.
6. You — Generate output.
See "Building Output" on page 457.
7. You — Provide the developer with a copy of the Help output files.
See "Distributing Output" on page 469.
8. Software developer — "Hooks" application interface or Web links to online topics.
The developer connects the dialogs, windows, or Web links to the appropriate online topics
using the information in the header file. See the online Help for more details about the
- 98 -
information that you might need to provide for the developer (depending on the output type
you generated).
9. Software developer — Creates a new build of the software application or publishes
updated Web links.
10. You — Install the new software build or view updated website. Test the CSH.
See "Testing Context-Sensitive Help" on page 124.
C SH Steps — If D eveloper Provides The H eader File
1. Software developer — Creates the header file.
2. Software developer — Provides you with a copy of the header file.
3. You — Add the developer's header file to the project.
See "Header Files" on the next page and "Importing Header Files" on page 103.
4. You — Add an alias file to the project.
See "Alias Files" on page 104 and "Adding Alias Files" on page 104.
5. You — Assign identifiers for the header file.
See "Creating and Assigning Identifiers" on page 112.
6. You — Associate the alias file with the target.
This is necessary only if you have created more than one alias file. See "Associating an Alias
File with a Target" on page 122.
7. You — Generate output.
See "Building Output" on page 457.
8. You — Provide the developer with a copy of the Help output files.
See "Distributing Output" on page 469.
9. Software developer — "Hooks" application interface or Web links to online topics.
The developer connects the dialogs, windows, or Web links to the appropriate online topics
using the information in the header file. See the online Help for more details about the information that you might need to provide for the developer (depending on the output type you
generated).
10. Software developer — Creates a new build of the software application or publishes
updated Web links.
11. You — Install the new software build or view updated Web links. Test the CSH.
See "Testing Context-Sensitive Help" on page 124.
- 99 -
MADCAP FLARE
Header Files
A header file is a simple text file that contains basic information about connecting the dialogs or windows in a software application to the corresponding topics in the Help system. Both you and the
software developer need access to this file.
A header file has an .h extension and is stored in the Project Organizer under the Advanced folder.
You can export the header file into other file formats (e.g., .bas, .properties, .inc) if necessary.
Note: A header file is sometimes referred to as a "map file."
W ho D evelops The H eader File A nd H ow?
Either you or the software developer is responsible for creating the header file. That is something you
must decide with the developer.
If it is decided that you are responsible for creating the header file, you can do so by adding a header
file to the project, adding an alias file to the project, and then creating and assigning identifiers.
W hat Is C ontained In A H eader File?
A completed header file contains one or more lines of text ("identifiers"). Each identifier refers to a
specific dialog or window that is linked to a corresponding topic in the Help system. Here is part of
a header file, showing three identifiers:
The following images provide a breakdown of what each part of an identifier means:
- 100 -
Note: If you have multiple header files in your project, their contents are merged when you generate output.
- 101 -
MADCAP FLARE
Adding Header Files
Aside from planning the context-sensitive Help (CSH), the first step in this process is to add the
header file to the Flare project. Exactly how you do this depends on whether you or the software
developer are responsible for creating the header file.
How to add a header file (if you are responsible for creating it)
1. Select Project>Advanced>Add Header File.
The Add Header File dialog opens.
n
n
3. In the File Name field, type a new name for the header file.
4. Click Add.
5. Click OK.
The header file is added to the Advanced folder in the Project Organizer. The Text Editor
opens to the right, with the page for the new header file (including an initial identifier)
shown.
6. You can close the Text Editor by clicking the x at the top-right corner of the tab.
You will not be entering content to this editor directly. It will be added automatically when
you work in the alias file. See "Creating and Assigning Identifiers" on page 112.
- 102 -
Importing Header Files
Not only can you add new header files to Flare, but you can also import existing header files (e.g.,
files with .h or .hh extensions).
How to import a header file
n
In the Project Organizer, right-click on the Advanced folder and select Add Header
File.
OR
n
Select Project>Advanced>Add Header File.
The Add Header File dialog opens.
2. Next to the Source File field, click
.
3. Find and select the header file that you want to import.
4. Click Open.
The Source File field now contains the path to the file that you are importing. Also, the name
of the file is displayed in the File Name field.
5. If you want to give the header file a different name than that for the imported file, click in the
File name field and replace the text.
6. Click Add.
The header file is added.
- 103 -
MADCAP FLARE
Alias Files
An alias file is used to populate a header file with the information necessary for producing contextsensitive Help (CSH). In Flare, you can open an alias file and use the Alias Editor to create and
assign identifiers for the header file. You can use a single alias file in a project for multiple header
files, or you can create a separate alias file to go with each header file.
An alias file has an .flali extension and is stored in the Project Organizer under the Advanced folder.
Adding Alias Files
After you add a header file to your project, the next step in creating context-sensitive Help (CSH) is
to add an alias file. The alias file will help you to add content to the header file.
How to add an alias file
1. Select Project>Advanced>Add Alias File.
The Add Alias File dialog opens.
n
n
3. In the File Name field, type a new name for the alias file.
4. Click Add.
5. Click OK.
The alias file is added to the Advanced folder in the Project Organizer. The Alias Editor opens
to the right, with the page for the new alias file shown (including an initial identifier for the
header file that you created previously).
- 104 -
Setting Identifier Options
When creating context-sensitive Help (CSH), you can set options for new identifiers in advance.
Doing this will supply some of the information (e.g., starting value, prefix, include topic in ID
name, assign skin) for you automatically as you create new identifiers. See "Creating and Assigning
Identifiers" on page 112.
How to set identifier options
1. Open an alias file.
2. In the local toolbar of the Alias Editor click
.
The Identifier Options dialog opens.
3. Complete any of the options as necessary.
n
Starting value Enter the starting value for identifiers that you create. Additional identifiers that are created will be incremented automatically based on that starting value.
- 105 -
MADCAP FLARE
n
- 106 -
Use Prefix Select this check box and enter a prefix to be added at the beginning of
each new identifier that you create (e.g., ID_, Dialog, Module1).
n
Include topic name in identifier name Select this check box if you want the
names of the assigned topics to be included automatically in the names of the new
identifiers.
- 107 -
MADCAP FLARE
n
- 108 -
Capitalize identifier names Select this check box if you want the name that is automatically added for new identifiers to use all caps.
n
Default skin Select this check box and from the drop-down field choose the skin that
you want to be assigned by default to new identifiers that are created. Of course, you
can always manually select a different skin for any identifier, but when you first create
a new identifier, it will initially be assigned to the default skin that you specified.
- 109 -
MADCAP FLARE
n
- 110 -
Primary Header Select this check box and from the drop-down field choose a specific header file, if you have more than one in your project. When you are working in
the Alias Editor, you can select a specific header file in the local toolbar. But what if
you do not select a header file and "(all identifiers)" is shown in the drop-down field in
the Alias Editor? In that case, the changes you make in the Alias Editor are applied to
the primary header file that you have selected in the Identifier Options dialog.
4. Click OK.
- 111 -
MADCAP FLARE
Creating And Assigning Identifiers
Creating and assigning identifiers means:
n
Creating topic IDs and unique numerical values that correspond to the different CSH Help topics that you want to include. For example, if the software application that you are documenting contains a dialog called the "Properties dialog," you might
have written a topic for it called "Using the Properties dialog." To connect the actual dialog
with your topic, you might create a topic ID in the Alias Editor, naming it "Properties_
Dialog." Furthermore, let's say that you have already created similar topic IDs for 157 other
topics and dialogs. You have given each of those topic IDs a unique number from 1 to 157. So
for "Properties_ Dialog," you assign number 158. Therefore, you end up with a topic ID and
numerical value that looks like this: Properties_Dialog 158.
n
Assigning a topic (or even a bookmark within a topic) to a topic ID that you
created. For example, if you have created a topic ID called "Properties_Dialog," you need to
somehow link it to the topic that you want users to see when they click the Help button in
that dialog. Let's say you want to link that topic ID with your topic named "Using the Properties dialog." Therefore, in the Alias Editor you could select the topic ID and then doubleclick the topic. This "ties" the topic ID to that specific topic.
n
(Optional) Assigning a skin to a topic ID that you create. For example, let's say that
you want most of the topics in your Help system to open in a window that is 5 inches wide
and 7 inches high (as well as other characteristics). Therefore, you create a skin that contains
those specifications and name it "Main." However, for CSH topics that are opened from
individual dialogs or windows, you want the Help window to be only 4 inches wide and 6
inches high (as well as other characteristics). So you create an additional skin containing
those specifications and name it "Dialogs." In the Alias Editor, you can click
and select the
Dialogs skin in the Identifier Options dialog. Then, whenever you create a new identifier, it
will automatically be associated with that skin. (You can also assign skins manually to each
identifier in the Alias Editor.)
The following steps show you how to do any of the following (use whichever set of steps best applies
to your situation):
n
Automatically generate identifiers for all topics
n
Create and assign identifiers to topics at the same time
n
Create identifiers only
n
Assign identifiers to topics only
- 112 -
How to automatically generate identifiers for all topics
1. Open the alias file that you created.
2. (Optional) You can set options for new identifiers in advance. This will supply some of the
information (e.g., starting value, prefix, include topic in ID name, assign skin) for you automatically as you create new identifiers. See "Setting Identifier Options" on page 105.
n
In the local toolbar of the Alias Editor click
.
OR
n
Right-click in the Identifiers side of the editor, and from the context menu select
Auto Generate.
The Generate Identifiers dialog opens.
4. In the Header area select one of the following, depending on whether you need to create a
new header file or have an existing one you can select:
n
After selecting a template, use the File Name field to enter a name for the new header
file.
n
Choose Existing This lets you choose an existing header file in your project. To use
this option, click the drop-down field and select a header file.
5. (Optional) In the Identifier Options area, you can override any of the values that are
already set in the Identifier Options dialog (see Step 2).
6. Click in the Generate Identifiers for field and select one of the following:
n
Unassigned topics only Select this if you already have some identifiers in the header
file that are assigned to topics. New identifiers will be created only for topics in your
project that are not yet assigned to an identifier.
OR
n
All topics Select this if you want new identifiers to be created for all topics in your
project, whether some topics are already assigned to new topics or not.
- 113 -
MADCAP FLARE
7. If you selected "All topics" in the previous step, click in the Existing Identifiers field and
select one of the following:
n
Keep Select this if you want to keep the identifiers that you already have in the header
file. As a result, you will have some topics that are assigned to multiple identifiers (the
old identifier and the new one).
n
Delete Select this if you want to delete the existing identifiers in the header file, creating new ones instead. This way, you will not have any topics that are assigned to
multiple identifiers.
8. Click Create.
New rows are added in the Alias Editor with
(instead of ) next to them. The green icon
indicates that the identifiers are assigned to topics. If you have previously set identifier
options (see Step 2), the identifier includes at least some of the appropriate information
already.
9. (Optional) If you want a certain identifier to point to a specific bookmark or header in the
assigned topic, do the following:
a. Select the identifier row.
b. Click
(located above the identifier list).
c. In the dialog that opens, select a bookmark or header.
d. Click OK.
10. (Optional) If you want to change an identifier name, click twice in the Identifier cell and
type the name (e.g., Properties_Dialog).
Note: Make sure you use underscores between words because spaces are not allowed.
11. (Optional) If you want to change the skin associated with an identifier, do the following:
b. Click the arrow in the Select skin button
and choose a skin from the drop-down.
(located above the identifier list)
12. (Optional) If you want to change the numerical value for an identifier, click twice in the
Value cell and type the new number.
Note: You may need to use the horizontal scroll bar at the bottom of the editor to see this
cell.
- 114 -
to save your work.
How to create and assign identifiers at the same time
2. (Optional) You can set options for new identifiers in advance. This will supply some of the
information (e.g., starting value, prefix, include topic in ID name, assign skin) for you automatically as you create new identifiers. See "Setting Identifier Options" on page 105.
3. If you have more than one header file in your project, click the down arrow at the top-left side
of the Alias Editor and select the header file for which you want to create identifiers. Otherwise, you can just leave "(all identifiers)" in the field.
What if you have multiple header files in your project and you do not select a header file, leaving "(all identifiers)" shown in the drop-down field? In that case, the changes you made in the
Alias Editor are applied to the primary header file that you have selected when setting identifier options.
4. On the left side of the Alias Editor, select one or more identifiers that you want to assign to
new identifiers.
You can use the "multi-view" to locate topics. If you use the options to split the view into two
halves, you can select multiple topics on the right side by holding down the SHIFT or CTRL
keys as you click.
- 115 -
MADCAP FLARE
n
Click
(located above the file list).
OR
n
Right-click on a topic on the left side of the editor, and from the context menu select
Assign Topic to New Identifier.
A new row is added with
(instead of ) next to it. The green icon indicates that the identifier is assigned to a topic. If you have previously set identifier options (see Step 2), the identifier includes at least some of the appropriate information already.
6. (Optional) If you want the identifier to point to a specific bookmark or header in the topic, do
the following:
- 116 -
b. Click
d. Click OK.
7. (Optional) If you want to change the identifier name, click twice in the Identifier cell and
8. (Optional) If you want to change the skin associated with the identifier, do the following:
9. (Optional) If you want to change the numerical value for the identifier, click twice in the
cell.
10. Repeat these steps for each identifier that you want to add (each one to represent a different
dialog or window in the software application).
to save your work.
- 117 -
MADCAP FLARE
How to create identifiers
2. If you have more than one header file in your project, click the down arrow at the top-left side
of the Alias Editor and select the header file for which you want to create identifiers. Otherwise, you can just leave "(all identifiers)" in the field.
What if you have multiple header files in your project and you do not select a header file, leaving "(all identifiers)" shown in the drop-down field? In that case, the changes you made in the
Alias Editor are applied to the primary header file that you have selected when setting identifier options. See "Setting Identifier Options" on page 105.
n
In the local toolbar click
.
OR
n
Right-click in the Identifiers side of the editor, and from the context menu select
New Identifier.
A new row is added with
(instead of ) next to it. The yellow icon indicates that the identifier is not yet assigned to a topic. If you have previously set identifier options (see Step 2),
the identifier includes at least some of the appropriate information already.
4. (Optional) If you want to change the identifier name, click twice in the Identifier cell and
5. (Optional) If you want to change the skin associated with the identifier, do the following:
6. (Optional) If you want to change the numerical value for the identifier, click twice in the
- 118 -
cell.
7. Repeat the these steps for each identifier that you want to add (each one to represent a different dialog or window in the software application).
to save your work.
- 119 -
MADCAP FLARE
How to assign identifiers to topics
2. (Optional) If you want to see only the identifiers that are not yet assigned to topics, click
in the local toolbar of the Alias Editor. This hides identifiers that are already assigned to topics in the editor until you click the button again.
3. On the right side of the Alias Editor, select an identifier that you want to assign to a topic.
4. On the left side of the Alias Editor, find a topic that you want to assign to the identifier that
you selected in the previous step.
You can use the "multi-view" to locate topics.
- 120 -
n
Double-click the topic.
OR
n
Click
(located above the file list).
OR
n
Right-click on the topic and from the context menu select Assign Topic to Selected
Identifier.
The topic name is added to the identifier row on the right side of the Alias Editor, and a green
icon
(instead of ) is displayed next to it. The green icon indicates that the identifier is
assigned to a topic.
6. (Optional) If you want the identifier to point to a specific bookmark or header in the topic, do
the following:
b. Click
d. Click OK.
to save your work.
- 121 -
MADCAP FLARE
Associating An Alias File With A Target
If you have added more than one alias file for your project, you need to associate the appropriate
alias file with the target that you plan to build. If you do not specify an alias file in a target, Flare
uses the first alias file listed in the Project Organizer.
How to associate an alias file with a target
1. Open the target.
2. In the Target Editor, click the Advanced tab.
3. Click the drop-down arrow in the Alias File field, and select the alias file that you want to
associate with the target.
- 122 -
to save your work.
Providing A Developer With A Header File
If it is decided that you are responsible for creating the header file (a file containing an .h extension
in your project), you must provide a copy of it to the software developer. The developer will then use
the header file to "hook" the numerical values in the header file to the appropriate dialogs or windows in the software.
When you are finished creating the header file, you can export it using the steps below so that the
developer has access to it. If you make further changes to the header file, you need to ensure that the
developer receives a new copy of it.
How to export header files
n
Select Build>Export Header File(s).
OR
n
In the Project Organizer, right-click the Advanced folder and select Export Header
File(s).
The Export Header Files dialog opens.
2. On the left side of the dialog, select the format(s) that you want to use for exporting the
header file(s). Work with your developer to determine the appropriate type of format.
n
C/C++ (.h) If this option is selected, a copy of the header file will be created with an
.h file extension.
n
Visual Basic (.bas) If this option is selected, a copy of the header file will be created
with a .bas file extension.
n
Java (.properties) If this option is selected, a copy of the header file will be created
with a .properties file extension.
n
Delphi Pascal (.inc) If this option is selected, a copy of the header file will be
created with an .inc file extension.
3. On the right side of the dialog, select the header file(s) to be exported.
4. Click the Browse button and select the location where the exported file(s) will be sent.
5. Click Export.
6. (Optional) If the file(s) are not in a shared location where the developer can retrieve them,
you need to copy the exported files(s) from that location and send them to the developer.
- 123 -
MADCAP FLARE
Testing Context-Sensitive Help
After you create context-sensitive Help (CSH), you should test it to verify that it works. You can do
this a couple of different ways, and it is not a bad idea to do both.
First, you can test your CSH identifiers from inside your project—using the Context-Sensitive Help
API Tester dialog. Second, you can test the CSH using a new build of the software application. The
following steps show you how to do both.
How to test context-sensitive Help from inside your project
n
If you want to test the CSH for the primary target, select Build>Test CSH API Calls
- Primary.
OR
n
If you want to test the CSH for a specific target, open the Project Organizer, right-click
a target under the Targets folder, and select Test CSH API Calls.
The Context-Sensitive Help API Tester dialog opens.
2. Next to each identifier, click
.
If the correct Help topic opens, the CSH link works.
3. Click Close.
Note: You can also see how each topic looks in a different skin by select a skin from the dropdown menu in the row and then clicking Test.
How to test context-sensitive Help using a build from the application
1. After the developer finishes "hooking" the identifiers in the application, obtain a new build
from the developer.
2. Launch the application build that you obtained from the developer.
3. Open a dialog or window that should be tied to a CSH topic.
4. Click the Help button in the dialog or window, or press F1 on your keyboard.
The Help topic associated with the dialog or window should open accordingly.
5. Test all of the CSH-related dialogs or windows in this same way.
- 124 -
Equations
Flare supports Mathematical Markup Language (MathML), which is a way to describe mathematical
notations in XML. Recommended by the Word Wide Web Consortium (W3C), MathML in Flare
allows you to embed virtually any kind of mathematical equation in the XML Editor.
Note: When you generate output, your equations are converted to images in the appropriate format. If you build PDF output, the equations are converted to vector images. If you build any
other type of output, the equations are converted to raster images (PNG files).
Note: When an equation is used in a heading and that heading is referenced in any way (e.g.,
cross-reference, table of contents entry), the equation is stripped from the reference.
Note: The Equation Editor contains its own online Help, which is separate from the rest of
Flare's online Help.
- 125 -
MADCAP FLARE
Creating And Inserting Equations
From any location in a content file (e.g., topic, snippet) you can create an equation (using the Equation Editor) and insert it into your content. In the markup the equation is contained in the <math>
tag, which is the MathML root of the equation. Although an equation may be comprised of many different parts, in the XML Editor it renders as a single block of content. In that way, it behaves much
like an image.
How to create and insert an equation
2. In the XML Editor place your cursor where you want to insert the equation.
n
Select Insert>Equation.
OR
n
On your keyboard press CTRL+E.
The Equation Editor opens.
4. In the editing area, create an equation, using the menus and toolbars as necessary.
The Equation Editor contains its own online Help, which is separate from the rest of Flare's
online Help. Therefore, if you need assistance with the features in the Equation Editor, use
the Help menu in that editor for more information.
hovers over the equation.
6. (Optional) In the Alternate Text field you can type alternate text to display when the equation is not available, such as when a disabled individual is using a screen reader.
For more information see the online Help.
7. Click OK.
The equation is added to the content file.
to save your work.
You can edit an existing equation. This includes the ability to change the equation itself, as well as
the way it looks. To do this, right-click on the equation and from the context menu select Edit
Equation. For more information, see the online Help.
- 126 -
External Resources
One of the ways Flare supports team collaboration is that you can create mappings to external
resources.
The External Resources window pane lets you select and maintain groups of external files that you
want to share among Flare projects. The paths of these files are written to the registry so they will be
available for all your Flare projects.
External resources can be virtually any local or network files that you have access to (e.g., images,
PDF files, Flare project files). From the External Resources window pane, you can easily bring external files into a project (i.e., a copy of the file is added to your Flare project) and keep them synchronized with the source files through mappings.
The external resources feature is ideal for shared files that you expect to change over time (e.g., logo
images, PDFs, style sheets), as opposed to, say, a template file that is simply copied into your
project and changed only in that project.
- 127 -
MADCAP FLARE
E X AMPLE
Let 's say y ou hav e a PDF cont aining emp loy ee cont act informat ion, and t he mast er
cop y of t his PDF resid es somewhere on a net work d riv e. You need t o inclu d e t his
PDF in one of y ou r Flare p roject s and link t o it from a t able of cont ent s (TOC ). But
t he PDF changes p eriod ically , and y ou need t o make su re y ou alway s hav e t he lat est
d at a.
Perhap s t he easiest way t o accomp lish t his is t o first ad d t he fold er cont aining t he
PDF t o y ou r Ext ernal Resou rces wind ow p ane.
Next , y ou can right -click on t he file and bring a cop y of it int o t he Flare p roject y ou
hav e op en.
- 128 -
- 129 -
MADCAP FLARE
Now t he cop y of t he PDF is in y ou r p roject and y ou can inclu d e a link t o it from a
TOC .
A coup le of mont hs lat er, y ou need t o generat e new ou t p u t from t he p roject . So in
t he Ext ernal Resou rces wind ow p ane y ou click t he bu t t on t o sy nchronize any
changed files.
- 130 -
And now t he p roject cont ains t he lat est changes t o t he PDF file.
- 131 -
MADCAP FLARE
Steps For U sing External R esources
Following are the primary steps that you will perform when it comes to external resources.
1. Add folders to External Resources window pane You can browse and select folders
containing files that you want to share among Flare projects. When you bring folders into the
External Resources window pane, this does not mean that they are automatically part of your
Flare project; it simply means that they are available to become part of a project and to be
synchronized with the source files residing elsewhere. See "Adding Folders to External
Resources" on the following page.
2. Copy and map files After you add folders to the External Resources window pane, you can
copy any of the files to your project, mapping them to the source files at the same time. See
"Copying and Mapping External Resource Files" on page 134.
This is a different process than that of importing files, which you can do elsewhere in Flare.
Files that are brought into a project using a traditional import process can be connected to
the source file, but only in one direction (i.e., files can be updated from the source to the
imported file in the project). On the other hand, files that are copied from the External
Resources window pane can be connected via mappings to the source files in two directions
(i.e., files can be updated from the source to the copied file or from the copied file to the
source).
3. Manage mappings When you work with external resource files, you should create mappings (connections) between the copies of external files that you bring into your project and
the source files outside of the project. You can do this at the point that you copy those files
into your project. You can also manage these mappings whenever necessary through the Map
Files and Folders dialog. This involves the ability to create, change, or remove mappings. See
"Managing Mappings of External Resource Files" on page 136.
4. Open and edit files You can open an external resource file by simply double-clicking it in
Flare. However, keep in mind that if you do this from the External Resources window pane,
you are opening the actual source file existing outside of your project. On the other hand, if
you double-click the file from the Content Explorer, you are opening the copy of the external
file. If you attempt to open a file type not supported in Flare, you will be directed to open the
file in its default application. For more information see the online Help.
5. Synchronize files After you map project files to source files located elsewhere, you can synchronize them to ensure that each file contains the same content. This process allows you to
import content from external files, export content from mapped files in the project, or keep
the most recently modified content. See "Synchronizing External Resource Files" on page 137.
If you attempt to synchronize files and Flare detects a conflict (i.e., a mapped file has been
modified both locally and in its mapped location), a dialog opens so that you can take the
appropriate action. For more information see the online Help.
- 132 -
Adding Folders To External Resources
You can browse and select folders containing files that you want to share among Flare projects.
When you bring folders into the External Resources window pane, this does not mean that they are
automatically part of your Flare project; it simply means that they are available to become part of a
project and to be synchronized with the source files residing elsewhere.
How to add folders to the External Resources window pane
1. Make sure the External Resources window pane is open. If it isn't, select View>External
Resources.
2. In the local toolbar, click
.
3. In the Select Folder dialog, find and select the folder that you want to add.
4. Click OK. The folder is added to the window pane.
- 133 -
MADCAP FLARE
Copying And Mapping External Resource Files
After you add folders to the External Resources window pane, you can copy any of the files to your
project, mapping them to the source files at the same time.
This is a different process than that of importing files, which you can do elsewhere in Flare. Files
that are brought into a project using a traditional import process can be connected to the source file,
but only in one direction (i.e., files can be updated from the source to the imported file in the
project). On the other hand, files that are copied from the External Resources window pane can be
connected via mappings to the source files in two directions (i.e., files can be updated from the
source to the copied file or from the copied file to the source).
How to copy and map external resource files
1. Make sure the External Resources window pane is open. If it isn't, select View>External
Resources.
2. Locate the file that you want to add to the project. You can use the "multi-view" to do this.
- 134 -
n
.
OR
n
Right-click on the file and from the context menu select Copy to Project.
4. In the dialog that opens, find and select the location in your project that you want to add the
file. Again, you can use the multi-view buttons to navigate to folders in your project.
5. Click OK.
6. In the Copy to Project dialog select Keep file synchronized (create mapping).
7. Click OK. The file is added to the project, as you can see by opening the Content Explorer. If
you selected to map the file, a small orange icon is shown next to it.
- 135 -
MADCAP FLARE
Managing Mappings Of External Resource Files
If you copy external resource files to your project, you can create mappings (connections) between
the copies of external files that you bring into your project and the source files outside of the project.
You can do this at the point that you copy those files into your project (see "Copying and Mapping
External Resource Files" on page 134 ). You can also manage these mappings whenever necessary
through the Map Files and Folders dialog. This involves the ability to create, change, or remove mappings.
How to manage mappings of external resource files
n
Select Tools>Manage Mappings.
OR
a. Select View>External Resources.
b. In the local toolbar click
.
The Map Files and Folders dialog opens.
2. Use the dialog to do any of the following:
Create/change a mapping:
a. If you are creating a new mapping, in the blank row click in the Project Path cell. If
you are changing an existing mapping, in the appropriate populated row click in the
Project Path cell.
b. In that cell click
.
c. In the dialog that opens, find and double-click the copy of the file located in your
project.
d. Click in the External Path cell.
e. In that cell click
.
f. In the dialog that opens, find and double-click the source file located outside of your
project.
Remove a mapping:
a. Click on the icon on the far left side of the row you want to delete. This highlights the
entire row.
b. At the bottom of the dialog click Remove.
3. Click OK.
- 136 -
Synchronizing External Resource Files
After you map project files to source files located elsewhere, you can synchronize them to ensure that
each file contains the same content. This process allows you to import content from external files,
export content from mapped files in the project, or keep the most recently modified content.
How to synchronize external resource files
n
Select Tools>Synchronize Mapped Files.
OR
a. Select View>External Resources.
.
The Synchronize Files dialog opens.
By default only files that are out of sync are listed. However, you can click
files that are already synchronized, and you can click
to refresh the list.
to also show
2. From the drop-down field at the top, select any of the following options:
n
Synchronize Files This imports external source files into the project, overwriting the
copies (if the external files have been modified most recently). And it also exports
copies of files in the project, overwriting external source files (if the copies in the
project have been modified most recently).
n
Import Files For all out- of-sync files, this imports external source files into the
project, overwriting the copies (regardless of which files have been modified most
recently).
n
Export Files For all out-of-sync files, this exports copies of files in the project, overwriting external source files (regardless of which files have been modified most
recently).
3. Make sure there is a check mark next to each pair of files that you want to synchronize and
click Synchronize.
4. In the message that displays, click OK.
Note: In the list of files, you can click
size.
to see more details, such as the modified date and file
- 137 -
MADCAP FLARE
Footnotes
A footnote is a comment that is used to explain a specific area of the text. It is used primarily for
print-based output. Both the area in the text and the comment contain a number or symbol that ties
the two together. A footnote comment is typically placed at the end of a page where the corresponding number or symbol is placed in the text. Otherwise, you can place a comment later in the
manual, such as at the end of a document, chapter, section, or book; in this case, the comment is
usually referred to as an endnote.
Tasks For Footnotes
Following are the primary tasks involving footnotes.
n
Inserting footnotes or endnotes You can insert a footnote marker at any spot in a topic.
When doing this, you can specify where the accompanying footnote text should be placed.
See "Inserting Footnotes" on the following page.
n
Editing footnotes or endnotes After inserting a footnote, you can edit it in various ways,
such as changing the text or modifying the look of the footnote number. You can also specify
whether footnote numbering should be restarted at a certain section or chapter. For more information see the online Help or the Flare Styles Guide.
- 138 -
n
Creating endnote proxies If you intend to consolidate your endnotes at the end of a manual, you can use an endnotes proxy. This proxy allows you to start the list of endnotes on a
new page. For more information see the online Help or the Flare Printed Output Guide.
Note: Footnotes are converted to popups in online output.
Inserting Footnotes
You can insert a footnote marker at any spot in a topic. When doing this, you can specify where the
accompanying footnote text should be placed.
How to insert a footnote
2. Place your cursor where you want to insert the footnote marker.
3. Select Insert>Footnote. The Insert Footnote/Endnote dialog opens.
4. In the first part of the dialog, you can select the location where the accompanying footnote or
endnote will be placed in the output. However, there is an alternative to selecting a location
from this list. In Step 5, you can select a style that can already have the footnote position
specified. If you select a style that has the footnote position specified, you do not need to
make a selection from this list.
n
End of Page This places the footnote comment at the end of the page where the intext footnote number is inserted.
n
End of Topic This places the footnote comment at the end of the topic where the intext footnote number is inserted. This is similar to the previous option. However, a single topic may result in multiple pages in the output. This option ensures that the footnote is placed at the end of the topic, not necessarily on the same page where the
corresponding number or symbol is placed.
n
End of Section This places the footnote comment at the end of the section where the
footnote number is inserted. You can create section breaks in the TOC Properties dialog
n
End of Chapter This places the footnote comment at the end of the chapter where
the footnote is inserted. You can create chapter breaks in the TOC Properties dialog
n
Endnote Proxy This is designed to place the footnote comment at a specific location
in the output, such as at the end of the book. It works in conjunction with an endnotes
proxy, which you create separately. The comment displays wherever you insert the endnotes proxy.
5. In the next area, you can select a style class for the footnote to determine its look and placement. The <MadCap:footnote> style is the default option. For more information about editing
footnotes and using styles, see the online Help or the Flare Styles Guide.
6. Click OK.
The footnote marker is added in the topic. The footnote comment area is added at the bottom
of the page or topic, depending on the footnote type you select.
- 139 -
MADCAP FLARE
Note: Like other markers, a footnote marker can be hidden in the editor so that only the
number can be seen. The marker is not shown in the output, whether you hide or show it
in the editor when you are working.
7. Click in the footnote area at the bottom of the page or topic and change the text as necessary.
8. (Optional) You can add other elements (e.g., images) and provide formatting for the content,
just as you would in a topic. If you have markers turned on ( View>Show>Show
Markers), you can right-click the footnote icon and select Footnote Properties from the
context menu. This allows you to select a format for the footnote number (e.g., uppercase
alpha, lowercase Roman), as well as specify other settings in the Footnote Properties dialog.
- 140 -
to save your work.
Glossaries
A glossary is a feature that you can add to your output to help users understand the meaning of
individual terms. You can include a glossary in both online and print-based output.
In online output, users can click a glossary term to see its definition in two ways:
n
Users can click the term in the output glossary pane (or tab).
n
Users can click the term in individual topics (if you specify that glossary terms should be converted to links). You have the flexibility of converting only certain terms that you have
marked, converting the first occurrence of terms in topics, or converting all occurrences.
A glossary XML file in Flare has an .flglo extension and is stored in the Project Organizer under the
Glossaries folder.
Text And Topic Definitions
The definition for a term can be simple text, which you supply at the same time that you create the
glossary term. However, you can also create a topic specifically for a definition (with any formatting
or elements that you might apply to a regular topic). The term can then be linked to that topic,
instead of linking it to a simple text definition.
Steps For Using Glossaries
Following are the steps necessary for creating a glossary and making it accessible to your end users.
1. Add/open glossary If you do not want to use the initial glossary provided by Flare, you can
add one. Otherwise, open the existing glossary from the Project Organizer to work on it. See
"Adding a Glossary File" on the next page or "Opening a Glossary" on the next page.
2. Create glossary terms and definitions After you add a new glossary or open an existing
one, you can create glossary terms and definitions. See "Creating Glossary Terms and Definitions" on page 143.
3. Create topic with glossary proxy If you are generating print-based output, you need to
insert a glossary proxy into a topic and make sure that topic has been added to the "outline
TOC." For more information see the online Help or the Flare Printed Output Guide.
4. Edit glossary You may need to edit the terms or definitions. You also may want to use
styles to change look of glossary elements. For more information see the online Help or the
Flare Styles Guide.
5. Enable glossary After creating the glossary terms and definitions, you need to enable the
glossary in the skin you want to use for the target. This step is necessary only for online output. See "Enabling Glossaries in Skins" on page 145.
6. Associate skin with target Now that the glossary is enabled in the skin, you need to associate that skin with the target you are building. This step is necessary only for online output.
See "Associating Skins with Targets" on page 412.
7. Associate master glossary with target Finally, you need to associate the glossary with a
target. After you build the target, the glossary will be incorporated into the output and terms
- 141 -
MADCAP FLARE
converted to links in individual topics (if you have selected one of the term conversion
options in the Target Editor). See "Associating Glossaries with Targets" on page 145.
Adding A Glossary File
Flare may provide you with an initial glossary called "MyGlossary," to which you add terms and definitions using the Glossary Editor. You can use this initial glossary, but you can also add more glossaries if you want.
How to add a new glossary file to a project
1. Select Project>Add Glossary.
The Add Glossary dialog opens.
n
n
3. In the File Name field, type a new name for the glossary.
4. Click Add.
5. Click OK.
The glossary is added to the Glossaries folder in the Project Organizer. The Glossary Editor
opens to the right, with an initial glossary term and definition shown.
Opening A Glossary
When you want to work on an existing glossary, use the following steps to open it.
How to open an existing glossary
2. Double-click the Glossaries folder.
- 142 -
The glossaries in your project are displayed.
3. Double-click the glossary that you want to open.
The Glossary Editor opens to the right.
Creating Glossary Terms And Definitions
After you add a new glossary or open an existing one, you can create terms and definitions. There
are two basic methods for creating glossary entries: (1) adding entries to the glossary directly, and
(2) inserting glossary term links. If you use glossary term links and generate print-based output ,
those links are converted to footnotes placed at the end of each page in the output.
With either of these methods, users will be able to access the terms and definitions in the output
Glossary pane (or tab). The difference between these methods lies in how they make definitions accessible through links (popups, hyperlinks, or expanding text).
A dding Entries To The Glossary D irectly
Use this method to simply add terms and definitions to a glossary.
How to add entries to the glossary directly
1. From the Project Organizer, open the glossary to which you want to add glossary entries.
2. In the local toolbar of the Glossary Editor, click
to add a new item.
A new row is added to the glossary, with "MyTerm" shown as the default name. The Properties dialog for the glossary term opens.
3. In the Terms section, replace the text "MyTerm," and type the new term.
4. In the Definition section, select either Text (if you want to provide a simple text definition
for the term) or Topic (if you have created a topic for the definition and want the term to link
to it). For print-based output, it probably makes the most sense to use the "Text" option.
5. If you selected "Text," type a definition in the space next to that option. If you selected
"Topic," click
, then find and select a topic.
6. Click the Style tab.
7. If you plan to generate online output, select one of the styles (Expanding, Popup, Hyperlink),
which dictates how the definition for the term is displayed in the output. (If you do not select
a style, Popup is used by default.)
n
Expanding Displays the definition in expanding text when the link is clicked.
n
Popup Displays the definition in a popup box when the link is clicked.
n
Hyperlink Opens the glossary page, from which the user can view the definition for
the term.
- 143 -
MADCAP FLARE
Note: These styles will take effect only if you have set the target to convert the glossary
terms (on the Glossary tab of the Target Editor). For more information see "Associating
Glossaries with Targets" on the following page.
Note: By default, glossary terms will not be converted to links if they are found in <h1>
through <h6> styles, as well as hyperlinks (i.e., content with the <a> tag). However, if
the same term is found in, say, a regular paragraph, the term will be converted to a link.
If you want to avoid certain terms being converted to links automatically (or if you want
to reverse this setting for <h1>-<h6> and hyperlink styles), you can use an option to
ignore glossary terms. For more information see the online Help.
8. Click OK.
to save your work.
Inserting Glossary Term Links
Use this method to select words and phrases in your topics that you want to add to the glossary.
The word or phrase is converted to a glossary term link, which lets users access the definition from
that location in the output. In print-based output, glossary term links are converted to footnotes at
the bottom of the page. After a glossary term has been added to the Glossary Editor, you can insert
subsequent glossary links even faster using the Glossary Terms window pane.
Note: You can also configure a target to convert existing glossary terms to links automatically.
For more information see "Associating Glossaries with Targets" on the following page.
How to insert glossary term links while creating new terms at the same time
2. Highlight the word or phrase that you want to add as a glossary term and link. Then select
Insert>Glossary Term Link.
The Create Glossary Term dialog opens.
3. If necessary, select the glossary on the right side of the dialog.
4. In the Definition field, type a definition for the term.
5. Click OK.
The word or phrase is now shown as a linked glossary term with an icon
The term and definition are added to the glossary.
- 144 -
to save your work.
beside it.
How to insert glossary term links for terms that have already been created
2. Select Tools>Glossary Terms.
The Glossary Terms window pane opens, listing all the terms already added to the glossary.
3. In the Glossary Terms window pane, double-click the term that you want to insert as a glossary link.
Make sure you double-click under the Term column. If you double-click anywhere else in the
row (under the Definition or File column), the Glossary Editor opens instead.
The word or phrase is now shown as a linked glossary term with an icon
beside it.
to save your work.
Enabling Glossaries In Skins
After you create glossary terms and definitions, you need to enable glossaries in the skin that you
intend to use for your target. This task is necessary only for online output.
How to enable a glossary in a skin
1. Open the skin from the Project Organizer. For more, see "Skins" on page 405.
2. On the General tab, click the Glossary check box so that it contains a check mark.
to save your work.
Associating Glossaries With Targets
One of the final steps to creating a glossary is to associate it with a target. After you build the target,
the glossary will be incorporated into the output.
How to associate a glossary with a target
2. In the Target Editor, click the Glossary tab.
3. (Optional) In the Glossary Term Conversion section, select one of the options if you want
to make use of glossary term links.
n
Do not convert terms In the output, none of the glossary terms that appear in topics will be converted to hyperlinks, popups, expanding text, or footnotes in the output
(even if a term was inserted into a topic as a glossary term link).
n
Convert only marked terms In the output, only glossary terms that were inserted
into topics as glossary term links will be converted to hyperlinks, popups, expanding
text, or footnotes in the output. Glossary terms that happen to exist in topics as normal text will not be converted.
n
Convert first occurrence of term In the output, only the first occurrence of a glossary term in a topic will be converted to a hyperlink, popup, expanding text, or
- 145 -
MADCAP FLARE
footnote in the output (per your instructions). This includes terms that were inserted
as glossary term links, as well as glossary terms that happen to exist in topics as normal text.
n
Convert all occurrences of
in a topic will be converted to
output (per your instructions).
links, as well as glossary terms
term In the output, every occurrence of a glossary term
a hyperlink, popup, expanding text, or footnote in the
This includes terms that were inserted as glossary term
that happen to exist in topics as normal text.
4. Click the check box next to each glossary that you want to associate with the target. A check
mark is added to the box.
5. (Optional for online output) In the Glossary Master Page section, select a master page to
be associated with your glossary definitions.
The master page will be used to display the glossary in the output. See "Master Pages" on
page 178.
- 146 -
to save your work.
Indexes
When your end users need to find specific information in your project, the three most common methods they use are: the search feature, a table of contents (TOC), and an index.
Unlike the search feature, the index is based on terms that you include in your project manually.
That way, when users look for terms in the index, the terms are linked only to topics that you think
are relevant for the user.
Benefits Of The Flare Method Of Indexing
Flare's method of producing an index includes the following benefits:
n
Prevents index keywords from pointing to deleted content Let's say you have
inserted an index keyword within a particular paragraph in a topic. Later, you decide to
delete the paragraph. Doing this also deletes the index keyword, so when the index is generated, that index keyword is no longer included in it. You do not have to remember to delete
the index keyword from another location or file.
n
Copies index keywords for you Let's say you have inserted an index keyword within a
particular paragraph in a topic. You then copy that paragraph and paste it into another
topic. When you do this, the index keyword is also copied, which means that you do not have
to worry about creating it again for that topic.
Online Index Versus Printed Index
An index in Flare works much like an index in a printed book. It provides key terms that point the
user or reader to specific locations where the information is stored. The main difference is that, in a
printed book, a reader must manually turn pages to get to the desired page listed in the index. In
online output, an end user simply clicks an item in the index and the item opens immediately.
Note: When you create print output, you can convert your online index to printed format.
When Should You Add Index Keywords?
There is no right or wrong answer to this. As you gain experience, you will develop your own work
habits that fit you best. Some authors add index keywords as they work on each topic. Other
authors wait until they are near the end of the development process and add index keywords all at
once. Here are a few benefits of waiting until the later in the process to add index keywords:
n
If you add index keywords as you create and work on each topic, it's possible that you will forget to add index keywords if you later make changes to a topic. If you wait until the later in
the process to add index keywords all at once, you are less likely to miss sections in topics.
n
You might find that your wording is more consistent if you wait to add all your index keywords at the same time. Projects can take months to develop, and over time it is easy to stray
from using consistent terms.
- 147 -
MADCAP FLARE
E X AMPLE
Early in t he d ev elop ment p rocess, y ou might st art u sing t he word "mod ify " in
sev eral ind ex key word s, bu t lat er on y ou might forget and st art u sing t he word
"change" inst ead . In t he end , some t op ics wou ld be connect ed t o ind ex key word s u sing t he word "mod ify , " while ot her t op ics wou ld be connect t o key word s u sing t he word "change. "
n
For authors who add index keywords all at once, Flare provides two features that can be quite
useful ("Index Entry Mode" and "saved layouts").
Keywords And Subkeywords
Keywords and subkeywords are the primary building blocks for an index. They are displayed in topics (as you edit them) as markers; each marker can hold multiple keywords.
Keywords are simply terms at the first level in an index. You might have a term that can be broken
down even further. In that case, you might decide to also create subkeywords, which are at the second-level in an index.
When you generate the output the index is automatically created based on these keywords and subkeywords. The keywords and subkeywords are visible to the end user in the generated index, but not
in the individual topics.
- 148 -
- 149 -
MADCAP FLARE
Steps For Using Indexes
Following are the main steps for creating an index and making it accessible to end users.
1. Create indexes In Flare there are a few different ways to create an index with keywords and
subkeywords.
n
Method 1—Add keywords to index and assign topics You can use the bottom
area of the Index window pane (select Tools>Index>Index Window or
View>Index Window ) to add index keywords and subkeywords (see "Adding Index
Keywords" on page 152) and assign topics to them (see "Assigning Topics to Index Keywords" on page 156 ). The major benefit of this method is that it is an easy and quick
way to place the same index marker at the beginning of multiple topics and maintain
better consistency in the index.
n
Method 2—Insert keywords in individual topics or snippets You can open a
topic or snippet and use the top area of the Index window pane to insert index keywords and subkeywords into that file (see "Inserting Index Keywords" on page 162).
The major benefit of this method is that it lets you place index markers at specific
places in a topic or snippet, as opposed to the very beginning of the file. While this
method allows you the most control, it takes more time than the other methods.
n
Method 3—Create auto-index You can automatically add words to an index by creating an auto-index. With this method Flare scans your project when you build output
to find certain words that you tell it to find. If those words are found, index entries are
added to the generated index automatically (see "Creating Auto-Indexes" on page 166).
The major benefit of this method is that it is quick and easy. However, it does not
allow you as much control as the other methods. You might select this method to give
you a starting place for an index and then use one of the other methods to add to it or
tweak it.
2. Create index links In addition to creating regular index entries that point to a specific
place in your project, you can also create index links. An index link is an entry in a generated
index that points to another entry. There are two kinds of index links—"See" and "See Also."
See "Creating Index Links" on page 169.
3. Enable index in skin (if generating online output) After inserting index keywords,
you need to enable the index in the skin you want to use for the target. See "Enabling Indexes
in Skins" on page 177.
4. Associate skin with target (if generating online output) Now that the index is enabled in the skin, you need to associate that skin with the target you are building. See "Associating Skins with Targets" on page 412.
5. Create topic with index proxy (if generating print-based output) An index proxy
serves as a placeholder for the index that will be created when you generate print-based output. You simply need to create a normal topic, add a heading to it if you want, and insert the
index proxy. Make sure that you add this topic to the location in your outline TOC where you
want the index to be placed. For more information see the online Help or the Flare Printed
Output Guide.
- 150 -
Note: If you are using chapter or volume auto-numbers and you want these numbers to
be reflected in a print index, you can do so by specifying the auto-numbers at the appropriate locations in your outline TOC (instead of inserting Chapter or Volume Number variables in a page layout). For more information see the online Help or the Flare Printed
Output Guide.
6. Modify index You can customize the way the index looks in your output. For more information see the online Help or the Flare Styles Guide.
Note: If you are used to creating indexes in RoboHelp, this process is quite different. In Flare
the index information is included in each individual topic, rather than in an index file that is
included in the project (RoboHelp method).
- 151 -
MADCAP FLARE
Adding Index Keywords
Use the following steps to add index keywords.
How to add an index keyword or subkeyword
n
Select Tools>Index>Index Window.
OR
n
Select View>Index Window.
OR
n
Press F9 on your keyboard.
The Index window pane opens. The window pane is split into two sections—the "Terms" area
at the top and the "Explorer" area at the bottom. If you want to see more or less of either section, you can click the splitter
between them and drag it up or down.
- 152 -
2. Do one of the following, depending on whether you are adding a first-level keyword or a second-level index keyword:
n
First-level keyword Right-click in the explorer area at the bottom of the window
pane, and from the context menu select Add Top-Level Keyword.
OR
n
Second-level subkeyword In the explorer area at the bottom of the window pane,
right-click on an existing top-level keyword. From the context menu select Add SubKeyword.
3. Type the index keyword as you want it to appear in the index and press Enter.
E X AMPLE
Let 's say y ou want t o ad d t he ind ex key word "Salad " t o some t op ics in y ou r p roject .
One way t o accomp lish t his is t o op en t hose t op ics and insert t he ind ex key word
int o t hem. Anot her way is t o op en t he Ind ex wind ow p ane, right - click any where in
t he exp lorer area at t he bot t om of t he wind ow p ane, and select Add Top-Le v e l
Ke yw ord.
- 153 -
MADCAP FLARE
- 154 -
Now let 's say t hat y ou want t o creat e a su bkey word called "C obb" u nd er t he t op lev el key word "Salad . " First , y ou right - click on S al ad and select Add S ub - Ke yw ord.
- 155 -
MADCAP FLARE
Assigning Topics To Index Keywords
After you add index keywords or subkeywords in the Index window pane, you can assign topics to
them. There are two methods for doing this.
n
Context menu in Index window pane
n
Drag from Content Explorer
How to assign topics to an index keyword or subkeyword—Index window pane
n
n
n
- 156 -
2. Right-click on the keyword or subkeyword and from the context menu select Assign Topic.
3. In the dialog that opens, find and select the topic(s).
If you want to select multiple topics, first click
in the local toolbar. Then double-click the
folder holding the files. You can hold the SHIFT key to select a range of files, or you can hold
the CTRL key to select individual files.
4. In the dialog, click Open.
Paths to the selected topics are displayed in the Index window pane after the keyword. And
an index marker is added at the beginning of each topic.
- 157 -
MADCAP FLARE
- 158 -
How to assign topics to an index keyword or subkeyword—Content Explorer
n
OR
n
OR
n
3. In the local toolbar of the Content Explorer, click the Show Files button
.
The window pane splits into left and right halves.
- 159 -
MADCAP FLARE
4. In the left half of the Content Explorer, click the folder holding the topics that you want to
assign to an index keyword.
5. In the right half of the Content Explorer, select the topics. You can hold the SHIFT key to
select a range of files, or you can hold the CTRL key to select individual files.
6. Drag the selected topics and drop them on the index keyword or subkeyword that is displayed
the bottom (explorer) portion of the Index window pane.
Paths to the selected topics are displayed in the Index window pane after the keyword. And
an index marker is added at the beginning of each topic.
- 160 -
- 161 -
MADCAP FLARE
Inserting Index Keywords
There are a few different ways to insert an index keyword into a topic or snippet, and each has its
own advantages.
n
Drag-and-drop
n
Quick term
n
Index window pane
n
Index entry mode
Does it matter where you insert an index keyword in a topic? Typically, you want to insert the index
keyword at the location closest to where the subject is discussed. One reason for this is to keep index
keywords accurate in print-based output. Let’s say you have a very long topic that discusses many
subjects and you have inserted all of the index keywords at the top of the topic. In print-based output it is likely that the topic will be spread out to multiple pages. With the index keywords inserted
at the top of the topic, the final index will point to the first printed page containing that topic,
rather than the exact page where the subject is discussed.
D rag-and-D rop Method
Use this method to quickly insert an index keyword that already exists in your project.
n
Advantage It is extremely fast.
n
Disadvantage The index keyword that you want to insert must already exist in the project.
This means you must first insert the index keyword into a topic using one of the other methods.
How to insert an index keyword using the drag-and-drop method
n
n
n
3. In the bottom (explorer) area of the Index window pane, click the index keyword and drag it
to the location in the topic or snippet where you want to insert it. As you drag the keyword
into the topic or snippet, a vertical red bar acts as a guide to help you place the keyword.
The index keyword is displayed within a marker in front of the word where you added it (as
long as markers are turned on).
- 162 -
to save your work.
Quick Term Method
Use this method to quickly insert the first word located after your cursor as an index keyword.
n
Advantage It is extremely fast.
n
Disadvantage It is not the method to use if you want to customize your phrase or add a second-level keyword. The word located immediately after the cursor is exactly what will be displayed in the index.
How to insert an index keyword using the quick term method
2. Click before or on the word that you want to insert as an index keyword.
3. Press F10 on your keyboard or select Tools>Index>Insert "<term>" (e.g., Tools>Index>Insert "software").
to save your work.
Index W indow Pane Method
Use this method to enter a keyword in the Index window pane.
n
Advantage It lets you customize the wording of the phrase in the index. It also lets you add
a second-level index keyword.
n
Disadvantage It is not quite as fast as the other methods.
How to insert an index keyword using the Index window pane method
2. Click at the location in the topic or snippet where want to insert an index keyword.
n
OR
n
OR
n
The Index window pane opens.
The window pane is split into two sections—the "Terms" area at the top and the "Explorer"
area at the bottom. If you want to see more or less of either section, you can click the splitter
- 163 -
MADCAP FLARE
4. Click in an empty field in the Terms column.
5. Type the index keyword as you want it to appear in the index.
If you want to add a second level to the keyword, type a colon after the first term, and then
type the second term.
E X AMPLE
If y ou t y p e Software:MadCap Flare, t he key word "Soft ware" ap p ears at t he
first lev el of t he ind ex, and t he t erm "Mad C ap Flare" ap p ears as a su bent ry
und er "Soft ware. "
6. Press Enter.
to save your work.
Index Entry Mode Method
Use this method to accomplish the same thing as the Index window pane method. The difference is
that, with this method, you do not need to move your cursor from the topic or snippet to the Index
window pane. You simply click at the spot in the text where you want to insert the keyword and
start typing. The words you type are added directly into the Index window pane. This is a good
method to use if you plan to do a lot of indexing all at once, without performing any other tasks in
the topic or snippet.
n
Advantage It is extremely fast and allows you to customize phrasing and add second-level
keywords.
n
Disadvantage It is not the best method to use if you want to perform indexing while also
adding other content and formatting to topics or snippets.
How to insert an index keyword using the index entry mode method
2. Select Tools>Index>Index Entry Mode . The cursor changes, displaying a small boxed "i"
next to it.
3. Click at the place in your topic where you want to add an index keyword.
4. Type the phrase that you want to add as the index keyword.
As you start typing, the Index window pane opens (if it was not previously opened), and the
phrase is added to the first empty field under the Terms column.
If you want to add a second level to the index keyword, type a colon after the first term, and
then type the second term.
- 164 -
E X AMPLE
If y ou t y p e Software:MadCap Flare, t he key word "Soft ware" ap p ears at t he
first lev el of t he ind ex, and t he t erm "Mad C ap Flare" ap p ears as a su bent ry
und er "Soft ware. "
5. Press Enter. The index keyword is displayed within a marker in front of the word where you
added it (as long as markers are turned on).
6. If you want to add more index keywords in the topic, repeat Steps 3-5.
to save your work.
Note: If you want to turn off the index entry mode and return to regular editing, select
Tools>Index>Index Entry Mode again.
- 165 -
MADCAP FLARE
Creating Auto-Indexes
Auto-indexes let you automatically add words in your project to a generated index, rather than
inserting all of the index markers manually. To do this, you can add phrases and corresponding
index entries to an auto-index file. When you generate the output, Flare scans the auto-index file
and adds the words it finds to the generated index.
E X AMPLE
Let 's say t hat y ou want t o make su re t hat t he word "Past a" ap p ears in y ou r generat ed ind ex, cont aining links t o all of t he t op ics where t hat word is fou nd . Your
first op t ion is t o manu ally insert t he "Past a" ind ex marker int o all of t hose t op ics.
Your second op t ion is t o ad d t he word "Past a" t o an au t o-ind ex file. When y ou generat e t he ou t p u t , Flare au t omat ically creat es ind ex ent ries and links for t he word s
and p hrases in y ou r au t o-ind ex file, inclu d ing t he word "Past a. "
How to create an auto-index
1. Select Project>Advanced>Add Auto-index Phrase Set. The Add Auto-index Phrase Set
dialog opens.
n
n
3. In the File Name field, provide a name for the auto-index phrase set file.
4. Click Add.
The Auto-index Editor opens in the middle of the interface. Also, the auto-index file (.flaix
extension) is added to the Advanced folder in the Project Organizer. In the future, you can
open the auto-index phrase set from there.
- 166 -
5. For each phrase in your project that you want to be automatically converted to a particular
index entry, complete the following steps in the Auto-index Editor.
a. In the local toolbar, click
the editor.
. The Properties dialog opens and a new row is added to
b. In the Phrase field, type the word(s) that you want Flare to find in your project and
use as the basis for a new index entry. Please note that the fields in this dialog are
case-sensitive; therefore, if you enter a phrase with the initial word capitalized, only
occurrences just like that in your topics will be used to create index entries.
c. In the Index Term field, enter the resulting word(s) to be added to the generated
index. If you want to create a multi-level index entry, separate the first-level term and
the second-level term with a colon.
E X AMPLE S
Let 's say t hat y ou ent ered pasta in t he Phrase field and Pasta in t he
Ind ex Term field . In t hat case, t he generat ed ind ex in t he p rint - based
ou t p u t will d isp lay like t his:
The ind ex ent ry p oint s t o any t op ics where t he lowercase inst ance of
"p ast a" has been fou nd . If y ou also want t he ind ex ent ry t o p oint t o
occu rrences where t he word is not all lowercase ("Past a"), y ou need t o
ad d anot her row t o t he Au t o-Ind ex Ed it or and creat e a p hrase for it (i. e. ,
ent er Pasta in bot h t he Phrase field and t he Ind ex Term field ).
Let 's say t hat y ou r p roject t alks abou t many kind s of p ast a and y ou
want t o creat e mu lt ip le ind ex ent ries for cert ain word s, some wit h single-lev el ent ries and ot hers wit h su blev els. For examp le, may be y ou want
Flare t o scan t he p roject for t he word "rigat oni. " When it find s occurrences, y ou might want a single-lev el ind ex ent ry like t his:
In t hat case, y ou wou ld ent er rigatoni in t he Phrase field and Rigatoni in t he Ind ex Term field . That ind ex ent ry wou ld p oint t o all of
inst ances of "rigat oni" in t he p roject . Bu t y ou also might want a mu lt ilev el ind ex ent ry d isp lay ed like t his:
- 167 -
MADCAP FLARE
In t hat case, y ou wou ld ent er rigatoni in t he Phrase field and
Pasta:rigatoni in t he Ind ex Term field .
d. Click OK.
- 168 -
to save your work.
Creating Index Links
In addition to creating regular index entries that point to a specific place in your project, you can
also create index links. An index link is an entry in a generated index that points to another entry.
There are two kinds of index links—"See" and "See Also."
E X AMPLE
Let 's say t hat y ou hav e writ t en sev eral t op ics abou t d ogs, and in each of t hose t op ics y ou hav e insert ed an ind ex marker labeled "Dogs. " Therefore, when u sers look in
t he ind ex u nd er "Dogs, " t hey will be able t o qu ickly find any of t hose t op ics. But
what if u sers d o not look u nd er "Dogs, " bu t rat her "C anines"?
There are a cou p le of op t ions t o solv e t he p roblem. First , y ou cou ld ad d ind ex
markers labeled "C anines" in all of t hose t op ics. A second op t ion is t o creat e an
ind ex link for "C anines" t hat p oint s u sers t o "Dogs. " In t he ou t p u t , it might look
somet hing like t his:
You can create index links in the following ways:
n
Using the Index Links Editor
n
Using the Index window pane
n
When inserting index markers
- 169 -
MADCAP FLARE
How to create index links using the Index Links Editor
1. Select Project>Advanced>Add Index Link Set.
The Add Index Link Set dialog opens.
n
n
3. In the File Name field, provide a name for the index link set file.
4. Click Add.
5. Click OK.
The Index Links Editor opens in the middle of the interface. Also, the index link file (.flixl
extension) is added to the Advanced folder in the Project Organizer. In the future, you can
open the index link set from there.
- 170 -
6. For each "See" or "See Also" index link that you want to create for a particular term, complete
the following steps in the Index Links Editor.
a. In the local toolbar, click
the editor.
. The Properties dialog opens and a new row is added to
b. In the Term field, type the term that you anticipate users may look for in the generated index. Please note that the fields in this dialog are case-sensitive; therefore, if
you enter a term in all lowercase letters, that is how it will be displayed in the output.
If you want to create a multi-level index entry, separate the first-level term and the second-level term with a colon (e.g., a single-level entry might be "Pasta"; a multi-level
entry might be "Pasta:rigatoni").
c. Select the kind of link—See or See Also.
Use a "See" link if the term in question does not exist in the project as an index marker.
The idea is that, if a user looks for that term in the index, you want to point the person
to a different term instead of the one originally sought. You can enter one "See" link per
term.
Use a "See Also" link if the term in question does exist as an index marker somewhere
in the project. The idea is that, if a user looks for that term in the index, you want to
point the person to a different term in addition to the one originally sought. You can
create as many "See Also" links for a term as you like.
d. In the Linked Term(s) field, enter the existing index entry that you want users to
look for. If you want to create a multi-level index entry, separate the first-level term
and the second-level term with a colon.
e. Click OK.
to save your work.
- 171 -
MADCAP FLARE
How to create index links using the Index window pane
n
OR
n
OR
n
2. Right-click in the explorer area at the bottom of the window pane, and from the context menu
select Add Index Link.
- 172 -
Note: In order to see this option in the context menu, you must already have at least one
entry in the index. Also, the option is not displayed if you right-click on the root Index
heading; you must right-click below it.
3. If you do not yet have an index link set in your project, the Add Index Link Set dialog opens;
continue with the next step.
If you already have an index link set in your project, skip to step 8. The index links you create
at this point will be added to the first index link set listed in the Advanced folder of the
Project Organizer (if there is more than one index link set).
n
n
5. In the File Name field, provide a name for the index link set file.
6. Click Add.
7. Click OK.
The Properties dialog opens. In addition, the Index Links Editor opens in the middle of the
interface. Finally, the index link file (.flixl extension) is added to the Advanced folder in the
Project Organizer. In the future, you can open the index link set from there.
8. In the Term field, type the term that you anticipate users may look for in the generated
index. Please note that the fields in this dialog are case-sensitive; therefore, if you enter a
term in all lowercase letters, that is how it will be displayed in the output.
If you want to create a multi-level index entry, separate the first-level term and the secondlevel term with a colon (e.g., a single-level entry might be "Pasta"; a multi-level entry might
be "Pasta:rigatoni").
9. Select the kind of link—See or See Also.
- 173 -
MADCAP FLARE
Use a "See" link if the term in question does not exist in the project as an index marker. The
idea is that, if a user looks for that term in the index, you want to point the person to a different term instead of the one originally sought. You can enter one "See" link per term.
Use a "See Also" link if the term in question does exist as an index marker somewhere in the
project. The idea is that, if a user looks for that term in the index, you want to point the person to a different term in addition to the one originally sought. You can create as many "See
Also" links for a term as you like.
10. In the Linked Term(s) field, enter the existing index entry that you want users to look for.
If you want to create a multi-level index entry, separate the first-level term and the secondlevel term with a colon.
11. Click OK.
- 174 -
to save your work.
How to create index links when inserting index markers
2. Click at the location in the topic where want to insert an index keyword.
n
OR
n
OR
n
The Index window pane opens.
4. Click in an empty field in the Terms column.
5. Type the index link using one of the following formats, depending on whether you want to
create a "See" or "See Also" link:
{nopage}My Entry{see}Linked Entry
{nopage}My Entry{seealso}Linked Entry
Use a "See" link if the term in question does not exist in the project as an index marker. The
idea is that, if a user looks for that term in the index, you want to point the person to a different term instead of the one originally sought. You can enter one "See" link per term.
Use a "See Also" link if the term in question does exist as an index marker somewhere in the
project. The idea is that, if a user looks for that term in the index, you want to point the person to a different term in addition to the one originally sought. You can create as many "See
Also" links for a term as you like.
E X AMPLE
Let 's say t hat y ou want t o see t his in t he ou t p u t :
In t hat case, y ou wou ld t y p e t his in t he Ind ex wind ow p ane:
{nop age}Insect s{see}Bu gs
If you want to add a second level to either index keyword, type a colon after the first term,
and then type the second term.
6. Press Enter.
- 175 -
MADCAP FLARE
The index keyword link is displayed within a marker in front of the word where you added it
(as long as markers are turned on).
to save your work.
Note: The second option (creating index links when inserting index markers) is not supported
in Microsoft Word or Adobe FrameMaker output.
Note: You also may want to use <span> styles to change the look of the index links. For example, you might want to make sure that the link term is displayed in bold to make it stand out.
For more information about using styles, including steps, see the online Help or the Flare Styles
Guide. For basic information about styles in this manual, see "Styles and Style Sheets" on page
362.
- 176 -
Enabling Indexes In Skins
After you insert index keywords, you need to enable the index in the skin that you intend to use for
your target.
How to enable an index in a skin
1. Open the skin from the Project Organizer. See "Skins" on page 405.
2. On the General tab, click the Index check box so that it contains a check mark.
to save your work.
- 177 -
MADCAP FLARE
Master Pages
A master page is an element that you can create in your project in order to apply certain content to
multiple topics. A master page is useful in online outputs, as well as print-based outputs. However,
the benefits are somewhat different for online output than they are for print output. For example,
you might use a master page in online output to apply features such as breadcrumbs, mini-TOCs, or
footer text to multiple topics, or even all topics in a target. For print-based output, a master page
allows you to determine page specifications (such as size or orientation) and to apply certain content (such as header text or page numbers) to many topics in a manual.
Page layouts are similar to master pages, but are more flexible and easier to use. The general rule of
thumb is that page layouts are recommended for print-based output (when possible), and master
pages continue to be the best method for automatically adding headers, footers, and breadcrumbs in
multiple topics for online output . Another difference between page layouts and master pages is that
page layouts can be used for any of the print-based outputs (Adobe PDF, XHTML, Microsoft XPS,
Microsoft Word, Adobe FrameMaker), whereas master pages can be used only for Microsoft Word
and FrameMaker when creating print-based output. See "Page Layouts" on page 275.
Like all other files in Flare, a master page is an XML file. It has an .flmsp extension and is stored in
the Content Explorer under the Resources\MasterPages folder.
Creating Master Pages
You can create master pages for use in both online and print-based output (Word and FrameMaker
only). Following are the primary tasks involved:
n
Adding a master page to a project You can add as many master pages as you want to a
project. However, you can associate only one master page with each target in your project.
n
Adding proxies to a master page Depending on the master page template that you
select, you might already have one or more types of proxies in your master page. Some of
these proxies are used primarily for online output (e.g., breadcrumbs), some are used for
printed output (e.g., glossary, index, TOC, page header, page footer), and some be used for
both online and printed output (e.g., body, mini-TOC). Some proxies are typically added to
topics, whereas others are usually inserted into master pages, and some (e.g., mini-TOC
proxies) can be used in either. Those that are most useful in master pages include the body,
breadcrumbs, mini-TOC, page header, and page footer proxies. See the online Help.
n
Removing proxies from a master page If you have a master page containing a proxy
that you do not want in the output, you can remove it from the master page.
E X AMPLE
If y ou want y ou r ou t p u t t o inclu d e only bread cru mbs and a foot er, y ou can
leav e t he bread cru mbs p roxy and bod y p roxy in t he mast er p age, and y ou can
remov e t he mini-TOC p roxy .
n
- 178 -
Adding header and footer content around a body proxy If you want your topics to
include a header or footer, you need to add content above the body proxy (for headers) or
below the body (for footers). Use the arrow keys on your keyboard to move the cursor above or
below the body proxy, then press Enter and type the content. For specific steps about headers
and footers for printed output, see the online Help.
How to add a master page to a project
1. Select Project>Add Master Page.
The Add New Master Page dialog opens.
n
n
More about the factory templates provided:
n
Glossary.flmsp This template is useful for creating a generated glossary.
n
MasterPage.flmsp This template is more common and is useful for creating header
and footer content for online output. For example, if you want to put your company's
logo or contact information on each page, this is a good template to choose. This template provides you with a breadcrumbs proxy, a body proxy, and mini-TOC proxy. The
breadcrumbs proxy generates "You are here" content, based on your table of contents
(TOC). The body proxy is replaced by your topic content in the output. And the miniTOC proxy is sort of the opposite of the breadcrumbs proxy, showing links to topics
that are lower than the current topic in the TOC hierarchy. You can delete either the
breadcrumbs proxy or mini-TOC proxy, but you should not remove the body proxy. If
you want to provide content such as your company's logo or contact information, you
can simply type that content above or below the body proxy, depending on whether
you want that content to display as a header or footer in each topic.
3. In the File Name field, type a new name for the master page.
4. (Optional) Click
. In the Stylesheet field, select a style sheet to associate with the new
topic. If you do not have a style sheet in your project, this field remains blank.
5. Click Add.
- 179 -
MADCAP FLARE
The Copy to Project dialog opens.
6. Click OK.
The master page file is added to the Resources\MasterPages folder in the Content Explorer.
The XML Editor opens to the right, with the new master page shown.
How to add a proxy to a master page
1. Open the master page.
2. Place your cursor at the location in the master page where you want to add a proxy.
3. Select Insert>Proxy>Insert[Type of Proxy].
Depending on the type of proxy you select, one of these dialogs opens: Body Proxy dialog,
Breadcrumbs Proxy dialog, MiniToc Proxy dialog, Page Header dialog, Page Footer dialog.
4. In the dialog, complete the available options, if necessary. Some options (e.g., Stylesheet
class) are optional. Click OK.
The proxy is added to the master page.
to save your work.
In some cases, you do not need to make any other changes to the master page; the content for the
proxies will be included automatically in the output as long as you associate the master page with a
target, or associate master pages with TOC entries (if producing printed output). However, you can
add content above or below any of the proxies.
How to remove a proxy from a master page
1. Open the master page.
2. Right-click the proxy bar that you want to delete. In the menu, select Delete.
The proxy is removed from the master page.
to save your work.
How to add a header or footer around a body proxy
1. Open the master page containing a body proxy.
2. Click to the left of the topic body proxy.
The horizontal cursor blinks above the proxy bar.
3. If you want to add a header, simply press Enter and add the content (e.g., text, picture,
ruler) for your header.
If you want to add a footer, press the down arrow on your keyboard until the horizontal cursor blinks below the topic body proxy (then press Enter and add content).
- 180 -
to save your work.
Opening Master Pages
After you create a master page, it is stored in the Resources folder of the Content Explorer (Content\Resources\MasterPages). At any time, you can open a master page and make modifications to
it. The master page displays in its own page of the XML Editor and remains accessible as you work.
How to open an existing master page
2. Double-click the Resources subfolder to open it.
3. Double-click the MasterPages subfolder to open it.
n
Locate and double-click the master page file (NameOfMasterPage.flmsp) that
you want to open. OR
n
Locate and click the master page file (NameOfMasterPage.flmsp) that you want
to open. In the local toolbar, click . The master page opens in its own page of the XML Editor.
Associating Master Pages With Targets
If you want a master page to be applied to all topics in the output, you would associate that master
page with the target that you are building. This is useful, for example, if you want to create breadcrumbs, a mini-TOC, header content, or footer content for your online outputs (DotNet Help, HTML
Help, WebHelp, WebHelp Plus, WebHelp AIR, WebHelp Mobile).
How to associate a master page with a target
1. Open the target (in the Project Organizer, double-click the target under the Targets folder).
For more information about targets, see "Developing Outputs" on page 413.
2. In the Target Editor, click the Advanced tab.
3. Click the drop-down arrow in the Master Page field, and select the master page that you
want to associate with the target.
to save your work.
- 181 -
MADCAP FLARE
Movies
Not only can you explain concepts and tasks to users, but you can also show them through the use
of movies. You can insert links to MadCap Mimic movies. You can also embed Flash, Windows
Media, and QuickTime movies.
Mimic Movie Links
If you have MadCap Mimic installed, you can create videos to be displayed in the output format of
your choice—Mimic Movie Format (MMF), Microsoft Silverlight, or Adobe Flash.
After creating a Mimic movie, you can insert a link to it. The movie will open and play in the appropriate window (e.g., movies generated in MMF are viewed in the MadCap Movie Viewer or MadCap
Help Viewer). After you insert a movie link, a small movie frame icon
displays next to it. You can
insert movie links into topics, tables of contents, or browse sequences.
For steps on inserting Mimic movies links into topics, see "Inserting Mimic Movie Links into Topics"
on page 186. For steps on inserting movie links into TOCs and browse sequences, see the online
Help.
Note: When you insert a Mimic movie link, the appropriate movie files are not copied to your
project's content files. Instead, they are automatically copied to the output files when you generate the target.
You can insert links to Mimic videos generated in one of the following output types: Mimic Movie
Format (MMF), Microsoft Silverlight, or Adobe Flash. For more information not provided here, see
the MadCap Mimic online Help.
A bout The MadC ap Mimic Movie Format The Mimic Movie Format (MMF) is designed to be opened by users from their desktop, rather than
being accessed from a server. If you need to integrate your movies into a software application, MMF
is a good solution.
Following are some important characteristics of MMF:
n
Built-in navigation If you generate a project (as opposed to a standalone movie), navigation is automatically built in to the interface so that users can access all movies in the
project.
n
Compile time The time required to generate output in this format is typically much less
than it is for other formats.
n
Output file size The generated file size is much smaller in this format than it is for other formats.
n
Output file types The output consists of files using an .mcmovie extension (for individual
movies), and another file using an .mcmoviesys extension (when creating projects).
n
Viewer Movies can be viewed in the freely distributable MadCap Movie Viewer or the MadCap DotNet Help Viewer.
- 182 -
n
XML The output files are XML-based, so you can open them in any XML editor to modify
them.
In addition to generating the output, what other actions are required?
n
MadCap Movie Viewer You must also provide your end users with the freely distributable
MadCap Movie Viewer. If you are distributing MadCap Flare output with the DotNet Help format, your end users can use the freely distributable MadCap DotNet Help Viewer instead of
the MadCap Movie Viewer to see the integrated Mimic movies: http://madcapsoftware.com/downloads/redistributables.aspx.
A bout The Microsoft Silverlight Movie Format
The Silverlight format is designed by Microsoft. According to Microsoft, "Silverlight is a crossbrowser, cross-platform, and cross-device plug-in for delivering the next generation of .NET based
media experiences and rich interactive applications for the Web."
Following are some important characteristics of the Microsoft Silverlight format:
n
project.
n
Output file types The output consists of an HTM file (XML-based), as well as various ancillary files.
n
Skins You can edit the interface of the movie output (e.g., the navigation features) through
the use of skins, including language skins.
n
Viewer Movies can be viewed in a browser window.
n
XML The output files are XML-based, so you can open them in any XML editor to modify
them.
n
MIME type (from server) In order for end users to see Microsoft Silverlight movies delivered from a server, the MIME type must first be set up correctly. This is something that your
server administrator would need to do. You should provide the admin with the necessary
steps. See the Mimic online Help.
n
Silverlight (from desktop) In order for end users to see Microsoft Silverlight movies
locally on their desktop, they must have Microsoft Silverlight installed.
A bout The A dobe Flash Movie Format
The Adobe Flash format is a common method for adding animation and interactivity to Web pages.
Following are some important characteristics of the Adobe Flash format:
n
project.
n
Output file size The generated file size is somewhat small. The only output format with a
smaller file size is the Mimic Movie Format (MMF).
- 183 -
MADCAP FLARE
n
Output file types The output consists of files that use the .swf extension and XML-based
files using the .htm extension. In addition, various ancillary files are created to help display
the navigation. If you do not use an embedded skin, you can use the HTM files as the main
entry points to view the movie output. The HTM files are used to display the Flash video
(SWF), as well as the navigation for it. However, if you use an embedded skin, you can just
distribute the SWF file.
n
Skins You can edit the interface of the movie output (e.g., the navigation features) through
the use of skins, including language skins. With Flash output, you can use a regular skin or
an embedded skin, which integrates the navigation into the SWF file.
n
Java 5.0 Update 13 or later In order to take advantage of the Flash output format, you
need to install the Java Runtime Environment (JRE) before generating output. You can download the JRE from http://java.sun.com/javase/downloads/index.jsp.
n
Flash Player 10 Flash output from Mimic must be viewed on a browser with Flash Player
10 (minimum).
Note: Users might experience issues with skin buttons (i.e., buttons used for navigation) in
Flash output under certain circumstances. If you distribute Flash movie output from a Web
server, end users should not experience any problems with the buttons in the skin. However, if
you distribute Flash movie output, for example, on a CD so that end users can access the movie
locally, buttons in the skin may not function correctly when users open the movie in the HTM
file. If you create movie output that you intend to be opened locally—rather than via the Web—it
is recommended that you use MMF or Microsoft Silverlight instead of Adobe Flash.
- 184 -
Flash, Windows Media, And QuickTime Movies
You can insert Flash, Windows Media, or QuickTime movies directly into your Flare topics or snippets. See "Inserting Movies" on page 188.
There are two ways to do this. First, you can use the Insert>Multimedia option. When you use
this option, the movie is embedded into the topic or snippet. In addition, you can specify advanced
settings, such as whether to include controls with the movie (e.g., Play, Pause), whether to automatically start the movie when it displays, and audio levels. The options available depend on the
type of movie you are inserting (Flash, Windows Media, or QuickTime).
Second, you can use the Insert>Hyperlink option. When you use this option, the user must click
the text link in order to open the movie. Also, you can choose to display the movie in another window.
Following are the video file types supported.
Flash file:
.swf
Windows Media files:
.asf
.asx
.avi
.mp4
.mpe
.mpeg
.mpg
.wm
.wmv
.wmx
QuickTime files:
.mov
.qt
Note: When you insert a movie from outside your project (using the Insert>Multimedia option),
a copy of the file is added to your project. The file is stored in the Resources\Multimedia folder
of the Content Explorer.
- 185 -
MADCAP FLARE
Inserting Mimic Movie Links Into Topics
If you have used Mimic to produce a movie, you can use this feature to create a link in a topic to the
movie's output. When you are finished, a link to the finished movie is inserted into the topic. When
a user clicks the link in the output, the movie plays in the appropriate window (e.g., movies generated in MMF are viewed in the MadCap Movie Viewer; Silverlight and Flash movies play inside
your online output).
How to insert a movie link into a topic
2. In the XML Editor, place your cursor where you want to insert the link.
3. Select Insert>Multimedia>Mimic Movie.
The Open dialog opens.
4. Find and select an individual Mimic movie or a movie project that you want to link to. You
can select any of the following types of files:
n
MIMOV This is an individual Mimic movie file (whether part of a project or standalone). When you want to work on an individual movie, you open this file.
n
MIPRJ This is the main Mimic project file, which contains one or more movie
(MIMOV) files. It is not required that you create a project in Mimic; it is simply an
option that you can use if you want to create a movie collection, as opposed to a standalone movie. Neither the MIPRJ nor the MIMOV files are finalized movies. They are
merely the files that are used to generate the finalized movies. When you want to work
on a movie project, you open the MIPRJ file.
n
MCMOVIE This is an output file that is created when you generate a movie (whether
the movie is part of a project or standalone). A Mimic project can contain several
movies. When you generate the finalized movies in Mimic, an MCMOVIE file is created
for each movie in the project (e.g., myfirstmovie.mcmovie, mysecondmovie.mcmovie).
The output plays in the MadCap Movie Viewer.
n
MCMV This is an optional output file that lets you view the movie(s) in the MadCap
Movie Viewer, rather than in a browser window.
n
MCMOVIESYS This is an output file that is created when you generate a movie
project (i.e., collection of related movies). The file is named after your project (e.g.,
myproject.mcmoviesys) and can be used as an entry point to view the movie collection.
The output plays in the MadCap Movie Viewer.
5. Click Open.
The Edit Mimic Movie dialog opens.
6. Change the options in the dialog as necessary:
n
n
- 186 -
File Displays the path to the movie or project file after you select it.
Lets you find and select a different movie or project file.
n
Format You can use this drop-down to select the type of output to be generated.
n
(default) The most appropriate movie format is used, based on the Flare output type that you generate. If you build a DotNet Help target, the movie uses
the Mimic Movie Format (MMF). If you build a HTML Help, WebHelp, or WebHelp Plus target, the movie uses the Microsoft Silverlight format. If you build a
WebHelp AIR target, the movie uses the Adobe Flash format. If you want to override these settings, select one of the specific movie types below.
n
MadCap Movie Player The movie is generated in MMF and displays in the
MadCap Movie Viewer or MadCap Help Viewer.
n
Adobe Flash The movie is generated in a Flash SWF file and displays inside
your Help system.
n
Microsoft Silverlight The movie is generated in the Microsoft Silverlight format and displays inside your Help system.
n
Style Class Select the kind of style class to be used for the link to affect the way it
looks and behaves. You can select the main hyperlink style tag (<a>) or a class of that
style.
n
Link Text Displays the text that you highlighted in the topic, which will be used as
the movie link. Leave the text as it is, unless you decide you would like to change it. If
you want to change the link text, type the new text in the field. It will replace the previously selected text in the topic.
If you do not provide link text, the file name for the movie or project will be used.
n
Screen Tip Type a phrase that will appear when the end user hovers over the movie
link in the output.
7. Click OK.
The movie link is added to the topic with a small movie frame icon
displayed next to it.
to save your work.
- 187 -
MADCAP FLARE
Inserting Movies
You can insert Flash, Windows Media, or QuickTime movies directly into your Flare topics or snippets.
There are two ways to do this—embedded and linked.
n
Embedded You can use the Insert>Multimedia option. When you use this option, the
movie is embedded into the topic or snippet. In addition, you can specify advanced settings,
such as whether to include controls with the movie (e.g., Play, Pause), whether to automatically start the movie when it displays, and audio levels. The options available depend on
the type of movie you are inserting (Flash, Windows Media, or QuickTime).
n
Linked You can use the Insert>Hyperlink option. When you use this option, the user
must click the text link in order to open the movie. Also, you can choose to display the movie
in another window.
How to insert a movie (embedded)
2. In the XML Editor, place your cursor where you want to insert the movie.
3. Do one of the following, depending on the type of file you want to insert:
n
Select Insert>Multimedia>Flash Movie.
OR
n
Select Insert>Multimedia>Windows Media Player.
OR
n
Select Insert>Multimedia>Quicktime Movie.
The Insert Multimedia dialog opens.
5. Select a movie file to insert. You can do this in various ways.
You can select a movie file already in the project by finding and choosing it in the Select File
structure, etc.
- 188 -
You can click
to find and select a movie file outside of the project.
If you want to select a movie file that you recently inserted somewhere in your project, click
Note: If you select a movie file outside the project, that file is then copied and placed
inside the project. The movie file is stored in the Resources\Multimedia folder of the Content Explorer.
6. (Optional) If you want to apply a specific style class to the movie, you can select it from the
Style Class field.
E X AMPLE
Let 's say t hat y ou hav e creat ed in y ou r st y le sheet a class of t he < object > t ag
called "BigMargin" (i. e. , object . BigMargin) and y ou hav e set t he margin for all
sid es of t hat class t o 1 inch. Rat her t han u sing t he d efau lt p arent < object > t ag
when y ou insert t he mov ie, y ou select object . BigMargin from t he St y le C lass
d rop -d own. As a resu lt , 1 inch of sp ace is ad d ed arou nd t he mov ie in t he out p ut .
user hovers over the movie link in the output.
8. (Optional) Select the Advanced tab and complete the options as necessary. The options
shown depend on the type of movie file you are inserting (Flash, Windows Media, QuickTime).
Flash options:
n
Quality Select the quality of the video, from "Low" up to "Best."
l
Low Favors playback speed over appearance and never uses anti-aliasing.
l
Auto Low Emphasizes speed at first but improves appearance whenever possible. Playback begins with anti-aliasing turned off. If the Flash Player detects
that the processor can handle it, anti-aliasing is turned on.
l
Auto High Emphasizes playback speed and appearance equally at first but sacrifices appearance for playback speed if necessary. Playback begins with anti-aliasing turned on. If the actual frame rate drops below the specified frame rate,
anti-aliasing is turned off to improve playback speed. Use this setting to emulate the View>Antialias setting in Flash.
l
Medium Applies some anti-aliasing and does not smooth bitmaps. It produces
a better quality than the Low setting, but lower quality than the High setting.
- 189 -
MADCAP FLARE
n
l
High Favors appearance over playback speed and always applies anti-aliasing.
If the movie does not contain animation, bitmaps are smoothed; if the movie
has animation, bitmaps are not smoothed.
l
Best Provides the best display quality and does not consider playback speed. All
output is anti-aliased and all bitmaps are smoothed.
Scale When you insert an embedded movie, a square container represents the area
where the video will be displayed. Just like a regular picture, you can resize the container either by using the settings on the Size tab or by clicking the clicking and dragging the icon
in the lower-right corner of the container. The settings in this field
determine how the video is displayed in the area represented by the square container.
l
Default (Show All) Makes the entire movie visible in the specified area without distortion, while maintaining the original aspect ratio of the movie. Borders
may appear on two sides of the movie.
l
No border Scales the movie to fill the specified area, without distortion but possibly with some cropping, while maintaining the original aspect ratio of the
movie.
l
Exact fit Makes the entire movie visible in the specified area without trying to
preserve the original aspect ratio. Distortion may occur.
n
Alignment Select where you want the video to be displayed within the container area
(e.g., Left, Right, Bottom, Bottom Right).
n
Auto play Select this option if you want the video to automatically begin playing
movie.
n
Loop Select this option if you want the movie to play repeatedly.
n
Show menu Select this option if you want to display the full menu, allowing the user
a variety of options to enhance or control playback. If you do not select this option, the
menu contains only the Settings option and the About Flash option.
n
Enable SWLiveConnect Select this option to specify whether the browser should
start Java when loading the Flash Player for the first time.
Windows Media options:
n
- 190 -
Player Controls Select an option for displaying the player controls (e.g., Play, Pause,
Volume).
l
Full Displays all of the available player controls.
l
None Does not display any player controls.
l
Mini Displays only some of the player controls (Play, Pause, Stop, Mute, Volume).
l
Invisible Hides the movie entirely, while still playing the audio. If you select
this option, you might want to resize the container square in your topic so that
it does not take up so much space in the output. The user will simply see blank
space where the container exists.
n
Auto start Select this option if you want the video to automatically begin playing
movie.
n
Full screen Select this option to display the movie using the entire screen.
n
Stretch to fit Select this option to automatically resize the movie so that it exactly
matches the size of the container area.
n
Play count Enter the number of times you want the video to repeat.
n
Audio Select options for the sound (mute, volume level, balance).
QuickTime options:
n
Scale When you insert an embedded movie, a square container represents the area
where the video will be displayed. Just like a regular picture, you can resize the container either by using the settings on the Size tab or by clicking and dragging the icon
in the lower-right corner of the container. The settings in this field determine how
the video is displayed in the area represented by the square container.
l
To Fit Automatically resizes the movie so that it exactly matches the size of the
container area.
l
Aspect Automatically resizes the movie so that it exactly matches the size of
the container area. However, the image is not stretched, but rather kept in its
original proportion. For example, the width of the movie might be increased to
match the width of the container area, but extra empty space might be shown
above and below the movie in order to compensate for the height of the container area.
l
Value Enter the value that you want to increase the display of the movie. If you
select 2, the movie will be twice as large as 1, and so on.
n
Show controls Select this option to show the player controls (e.g., Play, Pause).
n
Auto play Select this option if you want the video to automatically begin playing
movie.
n
Loop Select this option if you want the movie to play repeatedly.
n
Audio Select the volume level for the movie.
9. (Optional) Select the Size tab and complete the options as necessary to resize the container
area where the movie will be displayed. As an alternative, you can click and drag the icon
in the lower-right corner of the container.
To set a precise width and/or height:
n
In the Width and/or Height field of the Size section, provide the settings. First you
need to select Length in the top drop-down list. You can then enter a value in the
- 191 -
MADCAP FLARE
lower-left area and choose from several different units of measurement (points, pixels,
centimeters, etc.) in the lower-right area.
For example, if you want certain objects to be resized so that each is exactly 3
inches high, you can make sure that the width of each object is adjusted accordingly so that it stays in proportion. To do this, you would first set the height at 3
inches. Then for the width property, you would select Automatic (instead of
"Length") from the top drop-down list. In the same way, if you were to specify an
exact width, you could maintain the aspect ratio by setting the height to "Automatic."
To set the minimum width and/or height:
If the original object is smaller than the minimum width or height that is set, it will be
enlarged so that it reaches the minimum value. If the original object is larger than the minimum width or height, it will not be resized.
n
In the Width and/or Height field of the Minimum Size section, provide the settings. First you need to select Length in the top drop-down list. You can then enter a
For example, if you want certain objects to be resized so that they are at least 2
inches wide, you can make sure that the height of each object is adjusted accordingly so that it stays in proportion. To do this, you would set the minimum width
at 2 inches. You would then leave the minimum height property unspecified. In the
same way, if you were to specify a minimum height, you could maintain the aspect
ratio by not setting the minimum width property.
To set the maximum width and/or height:
If the original object is larger than the maximum width or height that is set, it will be reduced
in size so that it is no greater than the maximum value. If the original object is smaller than
the maximum width or height, it will not be resized.
n
In the Width and/or Height field of the Maximum Size section, provide the settings. First you need to select Length in the top drop-down list. You can then enter a
For example, if you want certain objects to be resized so that they are no more than
5 inches wide, you can make sure that the height of each object is adjusted accordingly so that it stays in proportion. To do this, you would set the maximum width
- 192 -
of the style at 5 inches. You would then leave the maximum height property
unspecified. In the same way, if you were to specify a maximum height, you could
maintain the aspect ratio by not setting the maximum width property.
10. (Optional) Select the Position tab and complete the options as necessary to determine how
the movie is positioned in the topic. You can select a Float and a Clear setting. You can also
set the Vertical Alignment of the object.
Float Use this field to specify where to place the object on the page.
n
None Does not place the object in a specific location.
n
Left Positions the object on the left side of the page frame, allowing you to type text to
the right of the object.
n
Right Positions the object on the right side of the page frame, allowing you to type
text to the left of the object.
n
Center of Column Positions the object in the center of the column on the page.
n
Outside Left Margin Positions the object beyond the left margin of the topic text.
n
Outside Right Margin Positions the object beyond the right margin of the topic
text.
n
Outside Frame Positions the object outside of the page frame.
n
Outside Frame, Top Align Positions the object outside of the page frame, as well as
aligning it with the top of the frame.
n
Left of Frame Positions the object to the left of the page frame.
n
Right of Frame Positions the object to the right of the page frame.
n
Center of Frame Positions the object both vertically and horizontally in the middle
of the page frame.
Clear Use this field to position an object so that it is "clear" of an adjacent object. For example, let's say you have already inserted an object and applied the float left property to it. If
you then insert another object immediately after the first object , you want to make sure that
the second object doesn't rest next to the first object. Instead, you want the second object to
be placed completely below the first object . Therefore, you can apply a clear property to the
second object.
n
None Does not apply the clear property to the object.
n
Left Side The object will be placed below the bottom outer edge of a previous object
that is floating left.
n
Right Side The object will be placed below the bottom outer edge of a previous object
that is floating right.
n
Both Sides The object will be placed below the a previous object, whether it is floating
left or right.
Vertical Alignment Use this field to adjust where the item is positioned vertically.
- 193 -
MADCAP FLARE
n
Baseline The baseline of the box will be aligned with the baseline of the parent box.
n
Text Top The top of the box will be aligned with the top of the parent element's font.
n
Text Bottom The bottom of the box will be aligned with the bottom of the line box.
n
Top The top of the box will be aligned with the top of the line box.
n
Middle The vertical midpoint of the box will be aligned with the baseline of the parent
box, plus half the x-height of the parent.
n
Bottom The bottom of the box will be aligned with the bottom of the line box.
11. (Optional) Select the Borders & Margins tab if you want to specify margins, padding, or
borders around the movie.
Margin: Click in any of the individual fields (Left, Right, Top, Bottom) to specify the settings for the margins around the object. If you click the down arrow to the right of all the
fields, the settings will be applied to all of the margin fields.
Padding: Click in any of the individual fields (Left, Right, Top, Bottom) to specify the settings for the padding. In the left side of the field, enter a number for the amount of padding.
In the right side of the field, select a unit of measurement (e.g., point, pixel, centimeter) for
the number you entered. If you click the down arrow to the right of all the fields, the settings
will be applied to all of the padding fields. When you click that down arrow, a small popup
displays.
Borders:
f. Click OK.
- 194 -
12. (Optional) Select the Background tab if you want to add background settings to a movie
interface. This includes the ability to specify a color, an image, and a repeating pattern for the
background image.
n
dialog.
a. Next to the Image field, click the Browse button.
b. Select an image file to insert and click OK.
c. If you want the background image to repeat, select one of the options from the Repeat
and Y fields.
13. Click OK.
The movie is added to the topic, represented by a gray square or rectangle, which is the area
where the video will be shown in the output.
to save your work.
- 195 -
MADCAP FLARE
How to insert a movie (linked)
1. Add the multimedia file to the project (Project>Add Multimedia).
3. In the XML Editor, highlight the text that you want to use as the link (or "hotspot") to the
movie.
5. From the Link to field select File in Project.
6. Navigate to the movie that you want to link to and select it.
options, see the online Help.
11. Click OK.
- 196 -
to save your work.
Navigation Links
A navigation link is a feature that points to additional information from a specific area in a topic.
The link may open information in the same topic, a different topic, or even a file outside of the
project altogether. With print-based output the link can electronically open the destination if the
user is viewing the manual online, depending on the type of output you create (e.g., XPS, PDF,
XHTML, Word). In addition, cross-reference links can be customized to refer to specific content and
page numbers in the printed manual (e.g., See "My Topic" on page 32). In Flare you can use navigation links in the following ways.
n
Cross-reference This is a navigation link that lets you connect text in one topic to another
topic (or a bookmark within a topic). This is somewhat similar to a text hyperlink. However,
cross-references differ from hyperlinks in a few ways. Cross-references let you create "automated" links that are based on commands you provide. You can keep links consistent and
change them in just one place by modifying the <MadCap|xref> style in a style sheet. See
"Cross-References" on page 200.
In addition, for print-based output , you can create context-sensitive cross-references. When
you use a context-sensitive cross-reference, the text automatically changes based on the relationship of the link and the target location if they are on the same page or only one page
away. See "Creating Context-Sensitive Cross-References" on page 210.
n
Text hyperlink This is a hyperlink applied to text that "jumps" to a location that you specify. See "Text Hyperlinks" on page 213.
n
Text popup This is a link that opens a popup box containing text that you provide. See
"Text Popups" on page 222.
n
Topic popup This is a link that opens a popup box containing another topic. See "Topic
Popups" on page 223.
n
Bookmark This is a marker you can apply to a specific location in a topic. Then you can add
a link that "jumps" to this specific location. See "Inserting Bookmarks into Topics" on page
215.
n
External link This is a link that lets you search for a file (e.g., HTM, HTML, XML, PDF,
Microsoft Office files) outside your project. This is especially useful if you want to link from
one topic to another in separate project outputs, such as CHM files. See "Inserting Links to
External Files" on page 216.
n
Image hyperlink This is a hyperlink that is applied to a picture rather than text. You can
also create an image map on a picture, thereby creating multiple links. See "Image Hyperlinks" on page 219 and "Creating Image Maps on Pictures" on page 220.
n
Movie link This is a link to a movie that was created by using MadCap Mimic or by inserting a Flash, Windows Media, or Quicktime movie. Including a movie in your Flare project
gives end users a richer learning experience. When a user clicks the movie link in the output,
the movie plays in the appropriate viewer. See "Movies" on page 182.
n
Audio link This is a link to an audio file that was created by inserting a Windows Media file.
See "Audio" on page 78.
n
Toggler This is a feature that lets you "toggle" between hiding and showing a tagged chunk
- 197 -
MADCAP FLARE
of content (e.g., paragraph, image, table, list, div). When users open the topic in the output,
they will see a link (also called a "toggler hotspot"). This hotspot can be any text in the topic.
When users click the hotspot, the hidden content is displayed. When users click the hotspot
again, the content becomes hidden once more. See "Togglers" on page 224.
n
Drop-down text This is a feature similar to a toggler. It lets you "scrunch up" content in
your topic. When the user clicks the drop-down text link, the content is displayed below it.
See "Inserting Drop-Down Text into Topics " on page 225.
For example, let's say you have a topic containing step-by-step procedures and it seems to be
getting quite lengthy. So you decide to condense the portion of the topic that contains the procedures. When users open the topic in the output, they will see a link (also called a "dropdown hotspot"). This hotspot is the first paragraph (or a section of the first paragraph) of the
drop-down effect. When users click the hotspot, the hidden content is displayed below the hotspot. When users click the hotspot again, the content becomes hidden once more.
n
Expanding text This is a feature similar to drop-down text. The difference is that, instead of
multiple paragraphs, you are condensing a single paragraph. You designate a portion of text
in a paragraph to serve as the expanding text hotspot. When users click the hotspot, the rest
of the paragraph is displayed. When users click the hotspot again, the rest of the paragraph is
hidden once more. See "Expanding Text" on page 226.
n
Concept link (also known as a "see also" link or "A-link") This is a navigation link
that lets users open topics that you've determined are related to the current topic. It is similar
to the related topics link. However, whereas you associate a related topics link with specific
individual topics (usually for a one-time use), you associate a concept link with a group of
topics (to be reused in different topics). One great benefit of this type of link is that, if you
later want to add or delete topics from the group, you only need to do so in one place and the
changes are applied to every topic containing that concept link. See "Inserting Concept Links
into Topics" on page 227.
E X AMPLE
Let 's say y ou are d ev elop ing a Help sy st em for an emp loy ee t ime- rep ort ing
soft ware ap p licat ion. You might hav e a grou p of relat ed t op ics (e. g. , C reat ing
a Time Sheet , C hanging a Time Sheet , Delet ing a Time Sheet ), and y ou want
each of t hose t op ics t o hav e t he same Help cont rol bu t t on t hat links t o t he
same t op ics. So y ou might creat e a concep t called "TimeSheet s. " You would
t hen insert t he key word int o each of t hose t op ics. Aft er t hat , y ou insert a concep t link int o each of t hose t op ics, select ing t he "Timesheet s" key word for t hat
link.
n
- 198 -
Related topics link This is a navigation link that lets users open topics that you've determined are related to the current topic. This is similar to a concept link. You should use a
related topics link if you are applying it to a topic that you want to associate with specific topics but you do not plan to reuse the same link in other topics. See "Related Topics Links" on
page 232.
E X AMPLE
Let 's say y ou hav e an int rod u ct ion t op ic for y ou r Help sy st em. You want t o
creat e a Help cont rol nav igat ion link at t he bot t om of t hat t op ic t hat links
users t o t hree ot her t op ics t hat y ou feel are p art icu larly u sefu l t o new u sers.
Howev er, y ou d o not int end t o u se t his same nav igat ion link in ot her t op ics.
So y ou d ecid e t o creat e a relat ed t op ics link becau se it is qu icker t han creat ing
a concep t link.
n
Keyword link (also known as a "K-link") This is a navigation link that lets users open
topics related to the current topic based on index keywords that they share. See "Keyword
Links" on page 230.
E X AMPLE
Let 's say y ou hav e insert ed an ind ex key word called "Accou nt ing d ep art ment "
t o some of t he t op ics in y ou r p roject , inclu d ing t he cu rrent t op ic t hat y ou are
working on. At t he bot t om of t his t op ic, y ou insert a key word link t hat
inclu d es t he "Accou nt ing d ep art ment " ind ex key word . In t he final ou t p ut ,
when u sers click t his Help cont rol, t hey can select and op en any t op ics t hat
also cont ain t he "Accou nt ing d ep art ment " key word .
n
Relationship link This is a navigation link that lets users open topics that you've determined are related to the current topic. This is similar to related topics links and concept
links. A relationship link is especially designed for DITA users; however, you do not need to
use DITA or know anything about it in order to use relationship links. A relationship table
can be created to identify which topics should be linked to one another. You then insert a relationships proxy into individual topics. In online output the end result is one or more hyperlinks that let users quickly open related topics. In print-based output the end result is one or
more references to related topics with the appropriate page number(s). See "Relationship
Tables and Links" on page 238 and "Inserting Relationship Links Into Topics" on page 260.
n
Shortcut control This is a navigation link that lets users launch a program or window in an
application that has a relationship to the current topic. See "Shortcut Controls" on page 261.
Note: Other features in Flare are also used to add navigation to a Help system. These features
are treated separately in this manual. They include tables of contents, indexes, and browse
sequences.
- 199 -
MADCAP FLARE
Cross-References
A cross-reference is a navigation link that lets you connect text in one topic to another topic (or a
bookmark within a topic). This is somewhat similar to a text hyperlink. However, cross-references
differ from hyperlinks in a few ways. They are based on format commands that help you keep the
look of links consistent and are especially useful for print output.
A utomating Links B ased On C ommands
Cross-references let you create automated links that are based on commands you provide. This
allows you to keep links consistent and change them in just one place by using the <MadCap|xref>
style. Commands are contained in brackets (e.g., {paratext}).
E X AMPLE
Let 's say y ou hav e a t op ic wit h t he t it le "Abou t Things, " and t here are sev eral ot her
t op ics in y ou r p roject t hat y ou want t o link t o t hat t op ic. Fu rt hermore, let 's say
t hat each one of t hose links need s t o hav e t he same t ext (e. g. , "For more informat ion see 'Abou t Things. '")
Now, y ou cou ld u se a t ext hy p erlink in each of t hose t op ics; t his wou ld be a good
op t ion if t he t ext in each of t he links need ed t o be d ifferent . Bu t inst ead y ou creat e
a cross- reference u sing t he < Mad C ap |xref> st y le. In t his st y le y ou sp ecify t he exact
t ext ment ioned abov e, along wit h t he {p arat ext } command , which d isp lay s t he t ext
of t he first p aragrap h it find s (su ch as a t op ic head ing). You can u se t hat cross- reference st y le any where t hat y ou 'd like t o creat e a link u sing t hat configu rat ion. When
y ou insert t he cross-reference it inclu d es t he t ext y ou p rov id ed (e. g. , "For more informat ion see"), and it u ses t he {p arat ext } command t o d isp lay t he head ing t ext for
t he d est inat ion t op ic (e. g. , "Abou t Things"). When y ou p u t it all t oget her, y ou hav e
"For more informat ion see 'Abou t Things. '"
Lat er, if y ou d ecid e t o change t he head ing t ext of t he d est inat ion t op ic t o "About
What chamacallit s, " t he cross-references will be u p d at ed au t omat ically when y ou generat e t he ou t p u t . The new head ing will au t omat ically be reflect ed in all of t he links
using t hat cross- reference st y le (i. e. , "For more informat ion see 'Abou t What chamacallit s'"). If y ou had u sed t ext hy p erlinks in a sit u at ion like t his, y ou would
need t o find and rep lace t he t ext in all of t he p ert inent links manu ally .
- 200 -
E X AMPLE
Here is an examp le of a cross-reference format , u sing a combinat ion of t ext and command s:
See {b}"{p arat ext }"{/b} on p age {p age}.
A format su ch as t his might be t ranslat ed in t he ou t p u t as somet hing like t his:
See "Dogs and C ats" on p age 9 3.
If you are using auto-numbers in your content (e.g., for figure or table numbers), you can create
cross-reference formats that include the auto-numbers. For more, see "Auto-Numbers" on page 364.
E X AMPLE
Let 's say t hat y ou hav e creat ed au t o-nu mbers in ord er t o nu mber all of t he figu res
in y our p roject . Perhap s y ou r au t o- nu mber format is set u p t o show t he word "Figure" followed by an increment ed nu mber and a colon (e. g. , Figu re 4 :, Figu re 5:, Figure 6 :). In ad d it ion, wherev er y ou ap p ly au t o- nu mbering in a t op ic, y ou might
manually t y p e a short d escrip t ion of t he image (e. g. , Prop ert ies Dialog). So in t he
ou t p ut u nd er t he grap hic, t he u ser might see somet hing like t his:
Figu re 4 : Prop ert ies Dialog
Now let 's say t hat y ou want t o insert a cross- reference in anot her t op ic t hat p oint s
t he user t o t he Figu re 4 grap hic. To d o t his, first of all y ou wou ld p robably want t o
insert a bookmark at t hat au t o- nu mber locat ion so t hat y ou can p oint d irect ly t o
t hat p aragrap h when y ou insert t he cross- reference. Then y ou can creat e a sp ecial
cross-reference format t hat inclu d es t he au t o- nu mber p ort ion of t hat p aragrap h. The
following t wo au t o-nu mber command s can be u sed :
{ paranum } This command d isp lay s all of t he cont ent in t he au t o- nu mber format ,
includ ing any t ext before an au t o-nu mber, t he au t o-nu mber it self, and any t ext aft er
t he aut o- nu mber. Using t he examp le p rov id ed abov e, t his command wou ld d isp lay
somet hing like t his in t he cross-reference:
Figu re 4 :
{ paranum onl y} This command d isp lay s any t ext before an au t o- nu mber and t he
aut o-number it self. Howev er, it d oes not show any t ext aft er t he au t o-nu mber (such
as a colon). Using t he examp le p rov id ed abov e, t his command wou ld d isp lay somet hing like t his in t he cross-reference:
Figu re 4
In ad d it ion, if y ou want t o inclu d e any t ext t hat y ou manu ally ad d in t he t op ic
aft er t he au t o- nu mber format , y ou can ad d t he { parate xt} command t o t he crossreference format . Using t he examp le p rov id ed abov e, t his command wou ld d isp lay
somet hing like t his in t he cross-reference:
- 201 -
MADCAP FLARE
Prop ert ies Dialog
Therefore, su p p ose y ou r ent ire cross-reference format is t his:
See "{p aranu m} {p arat ext }"
In t hat case, t he ou t p u t wou ld d isp lay somet hing like t his:
See "Figu re 4 : Prop ert ies Dialog"
On t he ot her hand , su p p ose y ou r ent ire cross-reference format is t his:
See "{p aranu monly } {p arat ext }"
In t hat case, t he ou t p u t wou ld d isp lay somet hing like t his (wit hou t t he colon):
See Figu re 4 Prop ert ies Dialog
Again, when y ou insert t he cross-reference in a t op ic, make su re y ou select t he format t hat y ou creat ed , and also remember t o link t o t he bookmarked p aragrap h
where t he au t o-nu mber ap p ears.
Tip: If you insert a cross- reference into a topic and it initially does not look the way you
expected, try updating the cross-references in the topic. See "Updating Cross-References" on page
212.
Tasks A ssociated W ith C ross-R eferences
You can do the following with cross-references.
n
Insert You can create new <MadCap|xref> styles, add commands, and add the cross- references to topics. See "Inserting Cross-References into Topics" on the following page.
n
Create context-sensitive cross-references For print-based output you can create context-sensitive cross-references, which automatically change the text in the link based on the
relationship of the cross-reference and the target location. See "Creating Context-Sensitive
Cross-References" on page 210.
n
Edit You can change the style and settings for a cross-reference. For more information see the
online Help or the Flare Styles Guide.
n
Update You can refresh your cross-reference links manually so that they display updated
information. See "Updating Cross-References" on page 212.
n
Single-source You can use style sheet mediums to single-source your cross-reference formats. For example, you can create a cross-reference format that displays as "See 'My Topic'"
in some outputs (e.g., online documentation) but as "See 'My Topic' on page 44" in other outputs (e.g., print-based formats). For more information see the online Help or the Flare Styles
Guide.
- 202 -
Inserting C ross-R eferences Into Topics
The following steps show you how to insert cross-references into topics.
How to insert a cross-reference into a topic—Standard method
2. In the XML Editor place your cursor where you want to insert the cross-reference.
3. Select Insert>Cross-Reference. The Insert Cross-Reference dialog opens.
4. From the Link to field, select a way to identify the topic or bookmark to which you want to
link. Based on the option you choose, the section below changes.
n
Topic in Project This option lets you search for a topic within your project. After you
select this option, use the area below to navigate to the file that you want to link to
and select it. By using the buttons in the local toolbar, you can view all files in a list,
view files in their folder structure, and use other options.
Shows all of the files in the project in a list in the area below. If you click the
button again, it switches to a folder tree view. In the list, you can click the
"File," "Type," or "Path" column headers to sort the list alphabetically by that
column data.
Shows or hides the files. If you click this button when the "Show Folders" button is selected, the area splits into two halves. The folder is shown on the left
side, and the files and subfolders within it are shown on the right.
If the "Show Files" button is the only one selected, you can click this button to
move up one folder level.
You can also click
n
to display and select any bookmarks within the destination topic.
Place in this document This option displays any headings and bookmarks in the
current file. After you click this option, use the section below to choose the heading or
bookmark to which you want to link.
- 203 -
MADCAP FLARE
5. In the Cross-Reference Properties section, select the <MadCap:xref> style that you want
to use for the cross-reference.
Initially, you may see only the parent <MadCap:xref> tag in the list. In the XRef Format area
to the right, you can see the current format associated with that tag. By default, it initially is:
- 204 -
See "{paratext}." The command {paratext} means that the text of the paragraphed bookmark—or the text of the first paragraph found in the topic—will be displayed at that spot.
You can: (1) use the parent <MadCap:xref> tag with its current format, (2) use the parent
<MadCap:xref> tag and change the format to something else, (3) create a new class of the
<MadCap:xref> tag and provide a custom format for it, or (4) use a class that you have
already created previously.
It is a good idea to create classes because you may eventually want to use multiple kinds of
cross-references in your project. Each class that you create can be used to display cross-references in a different format. For more information about using styles, including steps, see
the online Help or the Flare Styles Guide. For basic information about styles in this manual,
see "Styles and Style Sheets" on page 362. 6. If you want to use the parent <MadCap:xref> tag with its current format, or a class that you
have created previously, click MadCap:xref or the name of the class, respectively. Then continue with Step 13.
7. If you want to use the parent <MadCap:xref> tag but change the format, click MadCap:xref
and then Edit. The Edit Cross-Reference Style Class dialog opens. Continue with Step 10.
8. If you want to create a new class of the parent <MadCap:xref> tag, click New . The New
Cross-Reference Style Class dialog opens.
9. In the XRef Class field, give your new class a name.
10. In the Stylesheet to modify field, select the appropriate style sheet (if different from the
one shown). If you are using a master style sheet (recommended), only that style sheet is
shown in this field. If you are not using a master style sheet, the style sheet that you select
needs to be applied to the topic in which you are inserting the cross-reference.
11. In the Enter format field, provide the format for the style. This format can be a combination
of text that you type and automated commands that you select. You can select commands
from the list by double-clicking them. They are then added to the "Enter format" field.
Command
Description
b
Start bold text
/b
End bold text
bg
Start new background color
/bg
End background color
color
Start new text color
/color
End text color
default
Reset all font changes
ext
File extension
- 205 -
MADCAP FLARE
Command
- 206 -
Description
family
Start new font family
/family
End font family
file
File name, including extension
filename
File name, without extension
h1
Text of first heading 1 paragraph
h2
h3
h4
h5
h6
i
Start italic text
/i
End italic text
page
Page number
pagecount
Page count
pageref
Context-sensitive page reference
paranum
The auto-number text of bookmarked paragraph.
paranumonly
The auto-number only of bookmarked paragraph
paratext
Text of bookmarked paragraph
paraxml
Text and markup of bookmarked paragraph
path
File path
size
Start new font size
/size
End font size
sub
Start subscript text
/sub
End subscript text
sup
Start superscript text
Command
Description
/sup
End superscript text
title
Title of document
u
Start underlined text
/u
End underlined text
url
File path, URL syntax
E X AMPLE
If y ou want t he cross-reference t o inclu d e t ext (su ch as "For more informat ion
see"), simp ly t y p e it in t his field . You can also d ou ble- click any of t he command s t o ad d t hem t o t his field . For examp le, y ou might want t o ad d t he t ext
of t he first p aragrap h in t he d est inat ion file t o t he cross-reference format . The
command for t his is {p arat ext }. Descrip t ions for each command are d isp lay ed
in t he list .
Some command s inclu d e a st art t ag and an end t ag. For examp le, if y ou want
a p ort ion of t he cross-reference t o be d isp lay ed in bold , y ou wou ld p lace y our
cursor in t he "Ent er format " field where want t o st art t he bold font and d ou ble-click b in t he list below. Then p lace y ou r cu rsor where y ou want t he bold
font t o end and d ou ble-click /b from t he list .
So in t he end , y ou r cross- reference format might inclu d e a combinat ion of t ext
and mu lt ip le command s, su ch as:
For more informat ion see {b}{p arat ext }{/b}
A format su ch as t his one might d isp lay a link in t he ou t p u t like t his:
For more informat ion see M y De stination Topic
12. Click OK.
13. (Optional) In the Target Frame field of the Insert Cross-Reference dialog, click the dropdown arrow to select the way the linked destination will open. This option can be used to
open the destination topic or file in a popup. For descriptions of the options, see the online
Help.
user hovers over the cross-reference in the output.
When you enter a screen tip, it is added as a <title> tag in the markup. In addition, an <alt>
(alternate text) tag is added with the same text. This is useful when it comes to accessibility.
15. Click OK.
- 207 -
MADCAP FLARE
The cross-reference is added to the topic. You can change the appearance of the link (e.g.,
color, underline) by modifying the style (e.g., MadCap|xref or MadCap|xref.MyStyle) in the
Stylesheet Editor.
- 208 -
to save your work.
How to insert a cross-reference into a topic—Quick Cross-Reference method
2. In the XML Editor right-click at the location where you want to insert the cross-reference.
3. From the context menu select Quick Cross-Reference.
4. Select the appropriate submenu, depending on the option that helps you find the destination
the fastest.
n
Bookmarks Lets you select any bookmarks that you have already inserted into the current file.
n
Same Folder Lets you select any files that are contained in the same folder in the
Content Explorer.
n
Open Documents Lets you select any other files that are also currently open in the
workspace.
5. From the next submenu choose the bookmark or file.
The cross-reference is added to the topic. You can change the appearance of the link (e.g.,
color, underline) by modifying the style (e.g., MadCap|xref or MadCap|xref.MyStyle) in the
Stylesheet Editor.
to save your work.
- 209 -
MADCAP FLARE
C reating C ontext-Sensitive C ross-R eferences
For print- based output you can create context- sensitive cross- references, which automatically
change the text in the link based on the relationship of the cross-reference and the target location.
E X AMPLE
Let 's say t hat y ou hav e a cross- reference t hat is d esigned t o d isp lay t he t ext "See
Figure 2. 1. " If t he link and t he t arget fall on t he same p age, t he cross- reference is
up d at ed t o d isp lay t he t ext , "See Figu re 2. 1 abov e" or "See Figu re 2. 1 below. " If t he
link and t he t arget are on ad jacent p ages, t he cross- reference is u p d at ed t o d isp lay
t he t ext , "See Figu re 2. 1 on t he p rev iou s p age" or "See Figu re 2. 1 on t he next p age. "
If t he d ocu ment is d ou ble- sid ed wit h t he link on t he left p age and t he t arget on t he
right p age, t he cross-reference is u p d at ed t o d isp lay t he t ext , "See Figu re 2. 1 on t he
facing p age. "
Using context-sensitive cross-references is simply a matter of using the correct command. In other
words, instead of using the simple {page} command, you can use the {pageref} command.
E X AMPLE
Let 's say y ou u se t he p lain {p age} command . Perhap s t he comp let e format t hat y ou
creat e for a cross-reference st y le is t his:
See "{p arat ext }" on p age {p age}.
When y ou generat e t he ou t p u t , t his cross-reference will be conv ert ed t o somet hing
like t he following, regard less of where t he link falls in relat ion t o it s d est inat ion:
See "My Informat ion" on p age 4 2.
Howev er, let 's say t hat y ou u se a slight ly d ifferent format , somet hing like t his:
See "{p arat ext }" {p ageref}.
When y ou generat e t he ou t p u t , what y ou see in p lace of {p ageref} d ep end s on t he relat iv e closeness of t he link and t he d est inat ion. It might be t ranslat ed as any of t he
following:
See "My Informat ion" below.
See "My Informat ion" abov e.
See "My Informat ion" on p rev iou s p age.
See "My Informat ion" on p age 4 2.
- 210 -
How to create context-sensitive cross-references
1. Go through the process of inserting or editing a cross-reference. See "Inserting Cross- References into Topics" on page 203.
2. In the Insert Cross-Reference dialog, select either New or Edit, depending on whether you
want to create a new cross-reference style or edit an existing one.
3. Provide a format in the Enter format field. This format can be a combination of text and
automated commands.
When creating this format, make sure you include the {pageref} command in it. You can find
the command by selecting either Show All or Show Page Commands. When you find the
{pageref} command in the list, double-click it to add it to the format. Here is an example of a
format that contains a context-sensitive cross-reference command: See "{paratext}" {pageref}.
4. Click OK.
Note: You also have control over the text used in context-sensitive cross-references (e.g., instead
of the text displaying "on next page," it can be customized to display "on following page"). You
can customize this text through the use of a language skin. See the online Help.
- 211 -
MADCAP FLARE
U pdating C ross-R eferences
If you insert cross-references into topics and then later edit the formats for those cross-references (or
make other changes in the project that might affect them), you can update the cross-references in a
topic. By updating cross-references, you are essentially "refreshing" them so that they reflect any pertinent changes in the project since you inserted them.
Updating cross-references is not a mandatory step when it comes to the output. When you generate
output for a target , all of your cross-references in the output will be updated automatically. However, the cross-references in the source files in your project will remain as they were. But you can use
the following steps to manually update cross-references in a single content file, such as a topic or
snippet. This is a way of performing a "spot check" ahead of time, verifying that cross-references will
be updated accurately before you generate the output.
How to update cross-references
1. Open a content file (e.g., topic).
2. Select Tools>Update Cross-References.
The Update Cross-Reference dialog opens, displaying the destination topics of your cross-references.
3. Click Update.
- 212 -
Text Hyperlinks
A text hyperlink is one of the most basic forms of a navigation link. It is simply a hyperlink applied
to text. When an end user clicks the hyperlink in the output, the location specified in the hyperlink
opens. The location can be another topic in the project (including a bookmark within that topic), a
topic in an imported HTML Help file, or a file outside of the project (such as a website on the Internet).
You can create text hyperlinks in a couple of ways:
n
Standard You can use the "Standard" method, which allows you to select more options when
you insert the link, such as choosing a style class. This method lets you quickly select from a
list of files in your project or use a tree view with folders.
n
Quick You can use the "Quick Link" method, which is faster but does not have as many
options. This method lets you quickly select a bookmark in the current file, a file in the same
folder, or another file currently open.
How to insert a text hyperlink into a topic—Standard method
2. Highlight the text that you want to use as the link (or "hotspot").
4. From the Link to drop-down field select a way to identify the topic, bookmark, or file to
which you want to link. Based on the option you choose, the section below the field gives you
a list of selections or additional fields to complete. For descriptions of the options, see the
online Help.
hovers over the hyperlink in the output.
When you enter a screen tip, it is added as a <title> tag in the markup. In addition, an <alt>
(alternate text) tag is added with the same text. This is useful when it comes to accessibility.
7. (Optional) Next to the Style Class field click the Select button. This opens the Select Class
options see the online Help.
9. Click OK.
- 213 -
MADCAP FLARE
to save your work.
How to insert a text hyperlink into a topic—Quick Link method
2. In the XML Editor right-click at the location where you want to insert the hyperlink.
3. From the context menu select Quick Link.
4. Select the appropriate submenu, depending on the option that helps you find the destination
the fastest.
n
Bookmarks Lets you select any bookmarks that you have already inserted into the current file.
n
Same Folder Lets you select any files that are contained in the same folder in the
Content Explorer.
n
Open Documents Lets you select any other files that are also currently open in the
workspace.
5. From the next submenu choose the bookmark or file.
to save your work.
Note: You can edit text hyperlinks in at least three different ways: (1) edit the destination and
properties of the hyperlink, (2) edit the style of the hyperlink, and (3) unbind (or remove) the
hyperlink from the text. For more information see the online Help or the Flare Styles Guide.
- 214 -
Inserting Bookmarks Into Topics
A bookmark is a marker, or flag, that lets you create hyperlinks to specific locations within topics
(rather than to another topic file in general). You can insert a bookmark at a specific location in your
topic (e.g., at a subheading) and then insert a hyperlink that "connects" to that bookmark. This is a
useful feature, for example, if you have a somewhat lengthy topic and want the user to be able to
locate a specific place in the topic quickly.
How to insert a bookmark into a topic
2. Click in the topic where you want to insert a bookmark (e.g., in front of a subheading or a specific paragraph).
n
Select Insert>Bookmark.
OR
n
Press SHIFT+CTRL+K on your keyboard.
The Manage Bookmarks dialog opens.
4. In the New bookmark field, type a name for your bookmark (do not use spaces).
E X AMPLE
If t he bookmark is being p laced at t he beginning of a bu llet ed list of p rod uct
feat u res, y ou might t y p e ProductFeatures as t he bookmark name.
5. Click Add.
A bookmark icon
and the name of the bookmark are displayed at the appropriate location
in the topic (as long as your markers are turned on). (You can hide the bookmark name if you
want.)
to save your work.
7. Now you can insert a cross-reference or another kind of hyperlink elsewhere in this topic or in
another topic that links to this bookmark.
Note: You can also move an existing bookmark to a new location in the topic. To do this, place
your cursor in the topic where you want the bookmark to be moved. Select Insert>Bookmark.
In the Manage Bookmarks dialog, select the existing bookmark that you want to move (instead
of typing the name of a new bookmark). Then click Move.
- 215 -
MADCAP FLARE
Inserting Links To External Files
An external link lets you search for a file (e.g., HTM, HTML, XML, PDF, Microsoft Office files) outside your project. These steps involve a little planning ahead. You need to know the location where
your files will be published, as well as the names of your main output files.
How to insert a link to an external file
1. Open the content file (e.g., topic, snippet) where you want to insert the link.
2. Use the normal steps for inserting the type of navigation link that you want to create.
For example:
n
Text hyperlink See "Text Hyperlinks" on page 213.
n
Topic popup See "Topic Popups" on page 223.
n
Image hyperlink See "Image Hyperlinks" on page 219.
3. From the Link to drop-down field, select External File.
4. In the field to the right, next to the External File button, enter the appropriate link text,
depending on the output type you are using.
Note: Because the link usually needs to be relative, based on the final locations of your
output files, it is preferable to enter the text directly into the field, rather than clicking the
External File button.
If you are building HTML Help (CHM files):
Use one of the following:
NameOfOutput.chm::/NameOfTopic.htm
OR
mk:@MSITStore:PathToOutput\NameOfOutput.chm::/NameOfTopic.htm
Use the first method if you plan to publish your CHM files to the same folder. This is the recommended method.
Use the second method if you plan to publish your CHM files in different folders.
- 216 -
E X AMPLE S
Let 's say t hat y ou hav e a p roject called "First Help " and anot her called "Second Help . " Also, let 's assu me t hat t he first p roject will generat e a C HM file
named "First . chm, " and t he second p roject will generat e a C HM file named
"Second . chm. " (The names of t he C HM files can be sp ecified on t he G eneral t ab
of t he Target Ed it or. Simp ly ent er t he d esired name in t he Ou t p u t File field . If
y ou p lan t o p u blish t he files t o t he same fold er, t hey need t o hav e d ifferent
names. )
Sup p ose y ou want t o creat e a t ext hy p erlink in a t op ic called "Welcome, "
which is locat ed wit hin t he First Help p roject . When a u ser clicks on t his link,
y ou want it t o op en a t op ic called "Abou t t he C omp any , " which is locat ed
wit hin t he Second Help p roject . Therefore, y ou op en t he Welcome t op ic in t he
First Help p roject . Then y ou highlight t he t ext t o be u sed in t he hy p erlink, and
y ou select Inse rt>Hype rl ink . The Insert Hy p erlink d ialog op ens. Next , from
t he d rop - d own field y ou select E xte rnal Fil e . What d o y ou ent er in t he
E xte rnal Fil e field ?
We will t ake a look at t wo d ifferent sit u at ions. First , let 's say t hat y ou p lan t o
p ublish bot h C HM files t o t he same fold er (p erhap s on y ou r comp any 's int ranet ). In t hat case, y ou wou ld ent er t he following:
Second Help . chm::/Abou t t he C omp any . ht m
On t he ot her hand , let 's say t hat y ou p lan t o p u blish First . chm t o one fold er,
and y ou p lan t o p u blish Second . chm t o a sep arat e fold er, su ch as t he following: C :\Docu ment at ion\More Help . In t hat case, y ou wou ld ent er t he following:
mk:@MSITSt ore:C :\Docu ment at ion\More Help \Second Help . chm::/About
t he C omp any . ht m
Note: If you want to link content to an external CHM file, an alternative is to use the
"HTML Help File" option from the "Link to" field, instead of the "External File" option.
- 217 -
MADCAP FLARE
If you are building other output types:
Enter the relative path from the source output topic to the destination topic, using a pair of
periods to represent each folder level.
E X AMPLE
Let 's say t hat y ou hav e a p roject called "First Help " and anot her called "Second Help . " Su p p ose t hat y ou will generat e WebHelp ou t p u t for t he First Help
p roject and p u blish it t o a fold er called "My First Help . " You will also generat e
WebHelp ou t p u t for t he Second Help p roject and p u blish it t o a fold er called
"My Second Help , " which is locat ed next t o t he "My First Help " fold er. Now, let 's
say y ou hav e a t op ic called "Welcome" in t he First Help p roject and it is
st ored at t he root lev el of t he C ont ent fold er. You want t o creat e an ext ernal
link in t his t op ic so t hat it op ens a t op ic called "Abou t t he C omp any , " which
is st ored in t he root C ont ent fold er of t he Second Help p roject . In t hat case,
y ou wou ld ent er t he following when creat ing t he ext ernal link:
. . /. . /My Second Help /C ont ent /Abou t t he C omp any . ht m
5. In the link dialog, click OK.
to save your work.
7. Generate the output for the projects and publish the files to the appropriate location(s).
Note: With Mark of the Web enabled in your target, some links to external files may not work
properly in some versions of Internet Explorer when pages are viewed locally (file://). This is not
an issue if pages are viewed online (http://). For more information about MOTW, see Microsoft's
MSDN website.
- 218 -
Image Hyperlinks
After you insert a picture into a topic, you can turn that picture into a hyperlink, connecting it to
another topic, a topic in an imported HTML Help file, an external file (such as a website), or an
email.
How to insert an image hyperlink
2. In the XML Editor, right-click the picture that you want to use as a hyperlink.
3. In the context menu, select Hyperlink Picture.
The Insert Hyperlink dialog opens.
4. From the Link to drop-down field, select a way to identify the topic, bookmark, or file to
which you want to link. Based on the option you choose, the section below gives you a list of
selections or additional fields to complete. For descriptions of the options, see the online
Help.
dialog, which lets you apply one of the defined hyperlink styles (a.NameOfStyleClass) from
your style sheet to the link. After you select a style class in the dialog, click OK. The Style
Class field displays the selected style. (If you do not specify a style class, Flare uses the parent <a> style tag.)
linked destination will open. This option can be used to open the destination topic or file in a
popup. For descriptions of the options, see the online Help.
8. Click OK.
The hyperlink is added to the image in the topic. When a user hovers the cursor over the picture in the output, the cursor changes to a hand.
to save your work.
Note: You can edit image hyperlinks that you have inserted into a topic in the following ways:
(1) edit the destination and properties of the hyperlink, and (2) remove the hyperlink from the
image. For more information see the online Help.
- 219 -
MADCAP FLARE
C reating Image Maps On Pictures
After you insert a picture into a topic, you can create multiple hyperlinks for specific sections of the
image. This is called an "image map."
How to create an image map on a picture
2. In the XML Editor, right-click the picture on which you want to create an image map.
3. In the context menu, select Image Map. The Image Map Editor opens, with the picture displayed lightly.
4. In the Standard toolbar of the Image Map Editor, click one of the shape drawing buttons,
depending on the area of the picture that you want to use as a hyperlink:
Click this button if you want to draw an odd shape over a section of the image.
Click this button if you want to draw a rectangle over a section of the image.
Click this button if you want to draw a circle over a section of the image.
Note: There are additional features in the Image Map Editor that you can use to refine
your image map. For details about those features, see the online Help.
5. In the picture, click and drag your mouse over the area to be used as a hyperlink. Release the
mouse button when you are satisfied with the size and location of the shape. You should now
see the shape on top of the picture, connected by a series of points.
6. In the toolbar, click
. The Area Properties dialog opens.
which you want to link. Based the option you choose, the section below gives you a list of
Help.
linked destination will open. This option can be used to open the destination topic or file in a
popup. For descriptions of the options, see the online Help.
10. Click OK. The hyperlink is added to the image map.
11. If you want to add more hyperlinks to the image, select a shape button again and repeat the
steps above.
- 220 -
12. When you are finished creating hyperlinks on the image, click OK in the Image Map Editor.
The image map for the picture is completed and a small icon
displays on the picture.
to save your work.
- 221 -
MADCAP FLARE
Text Popups
A text popup is a link that opens a popup box containing basic text that you provide.
How to insert a text popup into a topic
2. In the XML Editor, highlight the text that you want to use as the link (or "hotspot") to open
the popup.
3. Select Insert>Text Popup.
The Insert Text Popup dialog opens, with the text that you highlighted already shown in "The
Hotspot Text" field.
4. In The Popup Text field, type the content for the popup.
5. Click OK.
The link for the text popup is added to the topic. You can change the appearance of the link
by modifying the <MadCap|popupHead> and <MadCap|popupBody> styles in the Stylesheet Editor.
to save your work.
Note: You can edit text popups that you have inserted into a topic in at least two different
ways: (1) edit the popup hotspot and text, and (2) edit the style of the text popup. For more
information see the online Help or the Flare Styles Guide.
- 222 -
Topic Popups
A topic popup is a text hyperlink that opens a topic or external file (such as a website) in a popup
box.
How to insert a topic popup into a topic
2. In the XML Editor, highlight the text that you want to use as the link (or "hotspot") for the
topic popup.
3. Select Insert>Topic Popup.
The Insert Topic Popup dialog opens. The Target Frame field at the bottom of the dialog
already has Popup Window selected.
which you want to link. Based on the option you choose, the section below gives you a list of
Help.
5. (Optional) The Link Text field displays the text that you highlighted in the topic, which will
it. If you want to change the link text, type the new text in the field. It will replace the previous text in the topic.
link. After you select a style class in the dialog, click OK. The Style Class field displays the
selected style. (If you do not specify a style class, Flare uses the "a.Popup" style class.)
8. In the Target Frame field, leave Popup Window as the selection.
9. Click OK.
The hyperlink for the topic popup is added to the topic. You can change the appearance of the
link by modifying the a.Popup style in the Stylesheet Editor. This includes the ability to
change the size of the popup.
to save your work.
Note: You can edit topic popups that you have inserted into a topic in at least three different
ways: (1) edit the destination and properties of the topic popup, (2) edit the style of the topic
popup, and (3) unbind (or remove) the hyperlink from the topic popup. For more information
see the online Help or the Flare Styles Guide.
- 223 -
MADCAP FLARE
Togglers
A toggler is a feature that lets you "toggle" between hiding and showing a tagged chunk of content.
When users open the topic in the output, they will see a link (also called a "toggler hotspot"). This
hotspot can be any text in the topic. When users click the hotspot, the hidden content is displayed.
When users click the hotspot again, the content becomes hidden once more.
How to insert a toggler into a topic
2. Click anywhere in the paragraph that you want to toggle (the content that will open when
users click the hotspot).
3. Select Format>Name.
The Manage Named Elements dialog opens.
4. Type a name for the toggled element (anything that will help you identify it).
5. Click OK.
The named element is added, with a yellow flag
next to it. The flag will not display in the
output. It is simply used to show you where a named element has been inserted. You can
hide or show this flag by selecting the option in the View menu.
6. In the topic, highlight the text that you want to use as the toggler hotspot.
7. Select Insert>Toggler.
The Insert Toggler dialog opens.
8. In the Toggler targets section, click the check box next to the toggler element that you
created.
9. (Optional) In the Toggler class section, select a style class to be associated with the toggler.
10. Click OK.
The toggler hotspot now has the toggler icon next to it in the XML Editor. (The icon will not
display in the output. It is simply used to show you where a named element has been
inserted.)
to save your work.
Note: You can edit togglers that you have inserted into a topic in at least three different ways:
(1) edit the content in the section that is "toggled," (2) edit the style of a toggler hotspot, and (3)
associate the hotspot with another toggler element and/or style class. For more information see
the online Help or the Flare Styles Guide.
- 224 -
Inserting Drop-Down Text Into Topics
Drop-down text is a feature that lets you "scrunch up" content in your topic. Let's say you have a
topic that seems to be getting quite lengthy. So you decide to condense the portion of the topic that
contains step-by-step procedures. When users open the topic in the output, they will see a link (also
called a "drop-down hotspot"). This hotspot is the first paragraph (or a section of the first paragraph) that you condensed. It might be something like "How to create a thingamajig." When users
click that hotspot, the hidden content (e.g., the actual steps to create the thingamajig) is displayed
below the hotspot. When users click the hotspot again, the content becomes hidden once more.
How to insert drop-down text into a topic
2. In the XML Editor type and format the content that will become the drop-down hotspot and
the drop-down body.
3. Highlight all of the paragraphs that you want to become the drop-down text, including the
first paragraph, which will contain the hotspot.
4. Select Insert>Drop-Down Text.
The Insert Drop-Down dialog opens. The entire first paragraph is displayed in the Drop-Down
Head field. The rest of the paragraphs are displayed in the Drop-Down Body section.
5. If you want only a portion of the first paragraph to be used as the hotspot link, highlight only
that specific text in the field (otherwise, leave the text in that field as it is).
6. Click OK.
The entire drop-down text section now has brackets around it in the XML Editor (if markers
are turned on). The hotspot has a blue down arrow to the left of it. If you designated just a
portion of the first paragraph to serve as the hotspot, smaller brackets surround it.
to save your work.
Note: You can edit drop-down text that you have inserted into a topic in at least three different
ways: (1) edit the content in the drop-down text, (2) edit the style of drop-down text, and (3)
unbind (or remove) the drop-down effect. For more information see the online Help or the Flare
Styles Guide.
- 225 -
MADCAP FLARE
Expanding Text
Expanding text is a feature that lets you "scrunch up" content in a paragraph in your topic. Let's
say you have a bulleted list in a topic. After each bullet is a feature of the software program that you
are explaining. You have given a detailed description of each feature, and now the topic seems to be
getting quite lengthy. So you decide to condense each bulleted item so that users initially see only
the name of the feature, which appears as a link (also called an "expanding text hotspot"). When
users click that hotspot, the hidden content (i.e., the rest of the paragraph) "expands" and is displayed after the hotspot. When users click the hotspot again, the content becomes hidden once
more.
How to insert expanding text into a topic
2. In the XML Editor type and format the content that will become the expanding text.
3. Highlight the paragraph (or the portion of it) that you want to become the expanding text
(including the word or words that will be used as the hotspot).
4. Select Insert>Expanding Text.
The Insert Expanding Text dialog opens. The paragraph (or the portion of it that you
selected) is displayed, with the first word highlighted. This first word will be used as the hotspot, unless you modify it by highlighting more of the paragraph.
5. If you want additional words in the paragraph to be used as the hotspot link, highlight them.
Otherwise, leave the text in that field as it is.
6. Click OK.
The selection is now surrounded by brackets in the XML Editor (if markers are turned on).
The hotspot appears with a small "T" and arrow next to it. The font used in the expanding
text depends on the settings specified for the <MadCap|expandingHead> and <MadCap|expandingBody> styles in your style sheet.
to save your work.
Note: You can edit expanding text that you have inserted into a topic in at least three different
ways: (1) edit the content in the expanding text, (2) edit the style of expanding text, and (3)
unbind (or remove) the expanding text effect. For more information see the online Help or the
Flare Styles Guide.
- 226 -
Inserting Concept Links Into Topics
After you create concepts keywords, you can insert concept links in topics.
A concept link lets users open topics that you've determined are related to the current topic. It is
similar to the related topics link. However, whereas you associate a related topics link with specific
individual topics (usually for a one-time use), you associate a concept link with a group of topics (to
be re-used in different topics). One great benefit of this type of link is that, if you later want to add
or delete topics from the group, you only need to do so in one place and the changes are applied to
every topic containing that concept link.
How to insert a concept link into a topic
1. Insert concepts into the appropriate topics.
E X AMPLE
If y ou hav e a sev eral t op ics t hat are all abou t d ogs (e. g. , how t o p ick a d og,
how t o t rain a d og, how t o groom a d og), y ou might insert a concep t called
"d ogs" in each of t hose t op ics t o t ie t hem t oget her. For more d et ails on concep t s, see t he online Help .
To add a concept:
a. Open the content file (e.g., topic, snippet).
b. Click at you the location where you want to insert the concept (a common location is
at the very beginning of the topic, in front of the topic title).
c. Select Tools>Concepts>Concept Window or press SHIFT+F9 on your keyboard.
The Concept window pane opens.
d. Click in an empty field in the Terms column.
e. Type the concept as you want it to appear in the concept link.
f. Press Enter. The concept is displayed within a marker in front of the word where you
added it (as long as markers are turned on). A marker can hold multiple concepts, but
most times you only need one keyword per topic.
g. Press CTRL+S or click
to save your work.
3. In the XML Editor, click in the topic where you want to insert the link (usually at the bottom
of the topic).
4. Select Insert>Help Control>Concept Link (A-link).
The Insert Concept Link Control dialog opens. The concepts that you have inserted into topics are listed on the left side of the dialog.
- 227 -
MADCAP FLARE
n
In the All Concepts section, double-click a concept that you want to add to the concept link.
OR
n
In the All Concepts section, click on a concept that you want to add to the concept
link. Then click
.
6. The concept is added to the "Selected Concepts" section on the right side of the dialog. Do
this for each concept that you want to add to the link. However, a concept link usually has
only one keyword associated with it (or just a few at the most). Remember, every topic containing any of those concepts will show up in the concept link in the output. A good practice
is to limit the number of topics per concept link. Otherwise, the link tends to lose its significance.
7. (Optional) If you want to specify other options for the control, click
and in the Concept
Link Options dialog select any of the following. Click OK to close the dialog when you are finished.
n
Style Class You can select the style class to be used for the control.
n
Label You can change the text shown on the control.
n
Display topics in You can specify that the links should be displayed in a popup
menu (same as default) or as a simple list.
Note: For projects that are merged, the list option is supported for standard merging (e.g., linking to an FLPRJ file in the table of contents). However, it is not supported for auto-merging in WebHelp Plus output.
n
Target Frame You can choose the type of frame used when a link is clicked.
n
(default) The destination file will open in the same window as the output window.
n
Parent Frame The destination file will open in the parent frame of the current
topic while hiding that topic.
n
New Window The destination file will open in a new browser window.
n
Same Frame The destination file will open in the same window frame as the
current topic.
n
Top Frame The destination file will open in the same output window, removing all other framesets. You might use this option, for example, if the destination topic has its own frameset.
n
Popup Window The destination file will open in a popup box on top of the current topic.
8. Click OK.
The concept link is added to the topic.
- 228 -
to save your work.
Note: You can edit a concept link by changing the concepts associated with it and by modifying
its style. For more information see the online Help or the Flare Styles Guide.
- 229 -
MADCAP FLARE
Keyword Links
A keyword link lets users open topics that are related to the current topic based on the index keywords that they share.
How to insert a keyword link into a topic
1. Insert index keywords into the appropriate files.
of the topic).
4. Select Insert>Help Control>Keyword Link Control (K-link).
The Insert Keyword Link Control dialog opens. The index keywords that you have inserted
into topics are listed on the left side of the dialog.
n
In the All Keywords section, double-click an index keyword that you want to add to
the keyword link.
OR
n
In the All Keywords section, click on an index keyword that you want to add to the
keyword link. Then click
.
The index keyword is added to the "All Keywords" section on the right side of the
dialog. Do this for each index keyword that you want to add to the link.
6. (Optional) If you want to specify other options for the control, click
and in the dialog
select any of the following. Click OK to close the dialog when you are finished.
n
Style Class You can select the style class to be used for the control.
n
Label You can change the text shown on the control.
n
Display topics in You can specify that the links should be displayed in a popup
menu (same as default) or as a simple list.
n
- 230 -
Target Frame You can choose the type of frame used when a link is clicked.
n
n
Parent Frame The destination file will open in the parent frame of the current
topic while hiding that topic.
n
n
Same Frame The destination file will open in the same window frame as the
current topic.
n
Top Frame The destination file will open in the same output window, removing all other framesets. You might use this option, for example, if the destination topic has its own frameset.
n
Popup Window The destination file will open in a popup box on top of the current topic.
7. Click OK.
The keyword link is added to the topic.
to save your work.
Note: You can edit a keyword link by changing the keywords associated with it and by modifying its style. For more information see the online Help or the Flare Styles Guide.
- 231 -
MADCAP FLARE
Related Topics Links
A related topics link lets users open topics that you've determined are related to the current topic.
This is similar to a concept link. You should use a related topics link if you are applying it to a topic
that you want to associate with specific topics but you do not plan to re-use the same link in other
topics.
There are a couple of methods do use for inserting related topics links. You can use the "drag-anddrop" method or the "Insert menu" method.
How to insert a related topics link using drag-and-drop
2. In the Content Explorer, click the Show Files button
.
3. On the left half of the Content Explorer, locate and select the folder containing the topics to
be included in the related topics link.
4. On the right half of the Content Explorer, select the topics to be included in the link. You can
hold down the CTRL or Shift key and click the topic file names to select individual topics or a
range of topics.
5. Drag the selected files to the appropriate location in the topic in the XML Editor.
As you drag the files, a colored vertical bar shows you where the link will be inserted when
you release mouse button.
6. Release the mouse button.
The Insert Related Topics Control dialog opens. The folders and topic files available in the
project are shown on the left. The files that you selected are automatically added to the section on the right.
7. (Optional) You can customize the related topics link in any of the following ways.
n
Bookmark If you want a link to point to a particular bookmark within a topic, do the
following:
a. In the Selected Topics area on the right of the dialog, click on the relevant
topic.
b. At the bottom of the dialog click
.
c. In the Select Bookmark dialog, click on a heading or bookmark within the topic.
If you select a heading, a bookmark will be created at that spot in the topic.
Note: If you want to remove a bookmark from the link, you can select the
bookmark in this dialog and click
. This removes the bookmark from the
link only; it does not remove the bookmark from the destination topic.
d. Click OK.
- 232 -
n
Style class If you want to select the style class to be used for the control, do the following:
a. At the bottom of the dialog click
.
b. In the dialog, click on the style class you want to use. The main style is "MadCap:relatedTopics," but if you create a class under that style in your style sheet,
it will be available for selection as well.
c. Click OK.
n
Label If you want to change the text shown on the control, do the following:
.
b. In the dialog, enter text in the Label field.
c. Click OK.
n
Popup menu or list If you want to specify that the links should be displayed in a
popup menu (default) or as a simple list, do the following:
.
b. In the dialog, click the down arrow in the Display topics in field and select
Popup Menu or List.
c. Click OK.
n
Target frame If you want to choose the type of frame used when the link is clicked,
do the following:
.
b. In the dialog, click the down arrow in the Target Frame field and select any of
the following:
n
n
Parent Frame The destination file will open in the parent frame of the
current topic while hiding that topic.
n
n
Same Frame The destination file will open in the same window frame
as the current topic.
n
Top Frame The destination file will open in the same output window,
removing all other framesets. You might use this option, for example, if
the destination topic has its own frameset.
- 233 -
MADCAP FLARE
n
Popup Window The destination file will open in a popup box on top of
the current topic.
c. Click OK.
n
Custom order If you want to specify that the links should be displayed in a custom
order (rather than alphabetically), do the following:
a. In the Selected Topics area on the right of the dialog, click on a topic that you
want to move up or down.
or
.
c. Click in the Use Custom Ordering field and select Yes.
Note: Custom ordering is not supported in DotNet Help output.
8. Click OK.
The related topics control is added to the topic.
- 234 -
to save your work.
How to insert a related topics link using the Insert menu
of the topic).
3. Select Insert>Help Control>Related Topics Control.
The Insert Related Topics Control dialog opens. The folders and topic files available in the
project are shown on the left.
4. On the left side of the dialog, either double-click a topic that you want to add to the related
topics control, or select the topic and click
. After doing this, the topic is added to the
Selected Topics area on the right side of the dialog.
You can use the "multi-view" to locate topics.
- 235 -
MADCAP FLARE
5. (Optional) You can customize the related topics link in any of the following ways.
n
Bookmark If you want a link to point to a particular bookmark within a topic, do the
following:
a. In the Selected Topics area on the right of the dialog, click on the relevant
topic.
.
c. In the Select Bookmark dialog, click on a heading or bookmark within the topic.
If you select a heading, a bookmark will be created at that spot in the topic.
d. Click OK.
n
Style class If you want to select the style class to be used for the control, do the following:
.
b. In the dialog, click on the style class you want to use. The main style is "MadCap:relatedTopics," but if you create a class under that style in your style sheet,
it will be available for selection as well.
c. Click OK.
n
Label If you want to change the text shown on the control, do the following:
.
b. In the dialog, enter text in the Label field.
c. Click OK.
n
Popup menu or list If you want to specify that the links should be displayed in a
popup menu (default) or as a simple list, do the following:
.
b. In the dialog, click the down arrow in the Display topics in field and select
Popup Menu or List.
c. Click OK.
n
Target frame If you want to choose the type of frame used when the link is clicked,
do the following:
.
b. In the dialog, click the down arrow in the Target Frame field and select any of
the following:
- 236 -
n
n
Parent Frame The destination file will open in the parent frame of the
current topic while hiding that topic.
n
n
Same Frame The destination file will open in the same window frame
as the current topic.
n
Top Frame The destination file will open in the same output window,
removing all other framesets. You might use this option, for example, if
the destination topic has its own frameset.
n
Popup Window The destination file will open in a popup box on top of
the current topic.
c. Click OK.
n
Custom order If you want to specify that the links should be displayed in a custom
order (rather than alphabetically), do the following:
a. In the Selected Topics area on the right of the dialog, click on a topic that you
want to move up or down.
or
.
c. Click in the Use Custom Ordering field and select Yes.
Note: Custom ordering is not supported in DotNet Help output.
6. Click OK.
The related topics control is added to the topic.
to save your work.
Note: You can edit a related topics control in various ways (e.g., by changing the topics associated with it, by modifying its style). For more information see the online Help or the Flare
Styles Guide.
- 237 -
MADCAP FLARE
Relationship Tables And Links
A relationship table is an element used to link related topics together. It is similar to concept links
or related topics links. Although a relationship table is a common feature in DITA, you do not need
to be using DITA or know anything about DITA in order to take advantage of relationship tables.
If you import content from DITA files that already contain relationship tables,
retained in Flare. You can also create new relationship tables in a Flare project
tionship proxies into individual topics. In online output, the end result is one or
that let users quickly open related topics. In print-based output, the end result is
erences to related topics with the appropriate page number(s).
those tables are
and insert relamore hyperlinks
one or more ref-
R elationship Table C omponents
Following are the basic components of a relationship table:
n
Columns By default, a relationship table has three columns, each named after three basic
topic types—Concept, Task, and Reference.
l
Concept Topics that contain basic information and descriptions about a subject.
l
Task Topics that provide step-by-step procedures for accomplishing something.
l
Reference Topics that provide detailed reference material.
If necessary, you can add more columns to a relationship table, naming the other columns
anything you want.
- 238 -
n
Rows You can have many rows in a relationship table, with each cell containing one or more
topic names, placed in the appropriate column. The relationships between the different topics
are defined across each row.
- 239 -
MADCAP FLARE
n
Relationship links When you insert topic references into a row in a relationship table,
those topics will link to the other topics in the row in some way.
Here are the types of links that you can create:
l
Normal (default) This is a two-way link. In other words, a link will be displayed in
each topic involved, and that link will open the other topic.
l
Source Only This is a link where the topic in question will have a link to other topics,
but other topics will not have a link back to it.
l
Target Only This is a link where the topic in question will not have a link to other
topics, but other topics will have a link back to it.
l
Use CONREF Target This uses the conref attribute to pull content. The conref attribute references an ID on content that can be reused. For Flare outputs other than DITA,
this option is not supported. For more detailed information about DITA and the conref
attribute, please refer to xml.coverpages.org/dita.html.
Unless you leave the default link setting, relationship links are identified by a blue background when you set them. To identify the exact kind of relationship link applied to an item,
you can select the item and then click the appropriate Properties button in the local toolbar.
You can specify links on individual topic items, on cells (which can contain multiple items),
or on entire columns.
- 240 -
l
Links on items Each topic item in a relationship table can use a different kind of
link.
l
Links on cells If you apply a link type to a cell, all of the topic items in that cell will
use that same setting (unless you later override the setting on individual items).
l
Links on columns If you apply a link type to a column, all of the topic items in all
cells will use that same setting (unless you later override the setting on individual
items or cells).
- 241 -
MADCAP FLARE
n
Groups You can group topics in the same cell so that they function as a unit or are related to
one another. When you group items together, you can choose a collection type to specify how
the items within the group behave.
Here are the collection types that you can use:
l
Unordered (default) This displays the grouped links in the output, but the order in
which they are displayed is not important.
l
Family This lets you display links not only to adjacent topics in the row, but to other
topics grouped within the same cell as well.
E X AMPLE
Let 's say y ou hav e a row t hat is p op u lat ed like t his:
Top ic A is in t he "concep t " cell.
Top ics, B, C , and D are cont ained in a grou p in t he "t ask" cell.
Top ic E is in t he "reference" cell.
Su p p ose y ou DO NOT u se t he Family collect ion t y p e. In t hat case, when
a u ser op ens Top ic A, he will see links t o Top ics B, C , D, and E. Howev er, when t he u ser op ens Top ic C , he will see links t o Top ic A and Top ic
E, bu t not t o Top ics B and D.
Now su p p ose y ou DO u se t he Family collect ion t y p e. In t hat case, when
a u ser op ens Top ic C , he will see links not only t o Top ics A and E, bu t t o
Top ics B and D as well.
l
Sequence This displays links with significance given to how the links are ordered in
the output. For Flare outputs other than DITA, this option is not supported. For more
detailed information about DITA and the sequence option, please refer to xml.coverpages.org/dita.html.
l
Choice This lets you specify which link should be "selected" or "highlighted" from the
group of links. For Flare outputs other than DITA, this option is not supported. For
more detailed information about DITA and the choice option, please refer to xml.coverpages.org/dita.html.
l
Use CONREF Target This uses the conref attribute to pull content. The conref attribute references an ID on content that can be reused. For Flare outputs other than DITA,
this option is not supported. For more detailed information about DITA and the conref
attribute, please refer to xml.coverpages.org/dita.html.
Unless you leave the default link setting, collection types are identified by a green background
when you set them. To identify the exact kind of group applied, you can select the item and
then click the appropriate Properties button in the local toolbar.
You can specify collection types on individual items in a group or on entire columns.
- 242 -
l
Collection types on items in groups Each group item in a relationship table can
use a different kind of collection type.
l
Collection types on columns If you apply a collection type to a column, all of the
groups in that column will use that same setting (unless you later override the setting
on individual groups).
- 243 -
MADCAP FLARE
- 244 -
n
Condition tags Like most everything else in Flare, you can apply condition tags to the elements within a relationship table. That is why you see squares next to the elements. If you
apply a condition tag to something (e.g., topic reference, group), the square will display the
color(s) associated with that condition tag. You can show or hide the condition tags if you
want.
R ules
Following are some basic rules when it comes to creating relationship tables:
n
Relationships are expressed within individual rows only. Relationships do not exist between
rows in a table.
n
Not every cell in a row needs to have a topic link.
n
Multiple topic links can be added to a single cell.
n
You can add the same topic link in many different rows.
R elationships Proxy
After you create at least one relationship table, you can insert a relationships proxy into the topics
where you want the links to appear in the output. When you build the output, the proxy is replaced
by the generated links.
- 245 -
MADCAP FLARE
- 246 -
B enefits
Follow are some of the primary benefits of using relationship links, as opposed to related topic links
or concept links:
n
You can create all of your link information in one place, in a single relationship table.
n
You can have multiple types of links at the bottom of topics (e.g., one for "Related Information," one for "Related Tasks," and one for "Reference Materials").
n
In online output, the links are automatically represented as hyperlinks. In print-based output, the links are automatically represented as a list of related topics with page number references.
- 247 -
MADCAP FLARE
Steps For U sing R elationship Tables
Following are the basic steps for using relationship tables:
1. Add The first step in using a relationship table is to add a new file to the Advanced folder in
the Project Organizer. You can add as many relationship table files as you need. Depending
on your project, you may need just one relationship table or many. For example, you might
want to use Relationship Tables 1 and 2 when generating Target A, but you might want to use
Relationship Table 3 when generating Target B. See "Adding Relationship Tables" on the following page.
2. Create After adding a relationship table file, you can create the actual content for it, adding
relationships between the topic links in a row. See "Creating Relationship Tables" on page
251.
3. Insert links You can insert a relationships proxy in the topics where you want links to
appear in the output, using the information contained in your relationship table(s). See
"Inserting Relationship Links Into Topics" on page 260.
4. Edit link styles You can edit the look of relationship links by adjusting the appropriate
styles in your style sheet. This might involve changing the look of any of the following: the
container holding the links, the heading(s) above the links, the link items themselves. For
more information see the online Help or the Flare Styles Guide.
5. Associate with target If you have created relationship tables in your project, you need to
tell Flare which tables to use for which targets. See "Associating Relationship Tables with Targets" on page 260.
- 248 -
A dding R elationship Tables
The first step in using a relationship table is to add a new file to the Advanced folder in the Project
Organizer. You can add as many relationship table files as you need. Depending on your project, you
may need just one relationship table or many. For example, you might want to use Relationship
Tables 1 and 2 when generating Target A, but you might want to use Relationship Table 3 when generating Target B.
How to add a relationship table file
1. Select Project>Advanced>Add Relationship Table.
The Add Relationship Table dialog opens.
n
n
3. In the File Name field, type a new name for the relationship table file.
4. Click Add.
5. In the Copy to Project dialog, click OK.
The relationship table file is added to the Advanced folder in the Project Organizer. The Relationship Table Editor opens to the right.
- 249 -
MADCAP FLARE
Opening R elationship Tables
The first step to creating a relationship table is to add a relationship table file to the Flare project.
After a relationship table file is added, you can open it at any time to work on it.
How to open a relationship table
2. Double-click the Advanced folder.
3. Double-click the relationship table file.
The Relationship Table Editor opens to the right.
- 250 -
C reating R elationship Tables
After adding a relationship table file, you can create the actual content for it, adding relationships
between the topic links in a row.
How to create a relationship table
1. Add a relationship table file (Project>Advanced>Add Relationship Table ) or open an
existing one (from the Advanced folder of the Project Organizer).
2. Use the editor to perform any of the following tasks. Keep the following in mind as you work:
n
Relationships are expressed within individual rows only. Relationships do not exist
between rows in a table.
n
Not every cell in a row needs to have a topic link.
n
Multiple topic links can be added to a single cell.
n
You can add the same topic link in many different rows.
For examples, see "Relationship Tables and Links" on page 238.
Give a row a name:
This simply helps you distinguish one row from another.
a. Click on a row.
.
c. In the Row Type field, enter a name.
d. Click OK.
Insert a new row:
n
.
- 251 -
MADCAP FLARE
Rename a column:
a. Click on any cell in the column you want to rename.
.
c. In the Column Type field, enter a name.
d. Click OK.
Insert a new column:
By default, a relationship table has three columns, each named after three basic topic types—
Concept, Task, and Reference. You can add more columns if you want.
n
.
Add a topic item to a cell:
a. Click on a cell where you want to insert a topic reference.
.
c. In the Open dialog, locate and double-click the topic. The topic file name is added to
that cell. The square next to the file name is used to show any condition tags applied
to the link.
- 252 -
Select the link type for a topic item, cell, or column:
When you insert topic items into a row in a relationship table, those topics will link to the
other topics in the row in some way. If you do not want to use the default type of link, you
can select another kind. You can do this for individual topic items, entire cells, or entire columns.
l
Links on items Each topic item in a relationship table can use a different kind of
link.
l
Links on cells If you apply a link type to a cell, all of the topic items in that cell will
use that same setting (unless you later override the setting on individual items).
l
Links on columns If you apply a link type to a column, all of the topic items in all
cells will use that same setting (unless you later override the setting on individual
items or cells).
Following are the steps for selecting link types.
a. Do one of the following:
n
For columns: Click in a column. In the local toolbar click
.
OR
n
For cells: Click in a cell. In the local toolbar click
.
OR
n
For topic link items: Click on a topic link item in a cell. In the local toolbar
click .
b. Click in the Linking field and select one of the following:
n
Source Only This is a link where the topic in question will have a link to other
topics, but other topics will not have a link back to it.
n
Target Only This is a link where the topic in question will not have a link to
other topics, but other topics will have a link back to it.
n
Normal (default) This is a two-way link. In other words, a link will be displayed in each topic involved, and that link will open the other topic.
n
None This option indicates that the topic reference does not have a link.
n
Use CONREF Target This uses the conref attribute to pull content. The conref
attribute references an ID on content that can be reused. For Flare outputs other
than DITA, this option is not supported. For more detailed information about
DITA and the conref attribute, please refer to xml.coverpages.org/dita.html.
Unless you leave the default link setting, relationship links are identified by a blue background when you set them. To identify the exact kind of relationship link applied to an
item, you can select the item and then click the appropriate Properties button in the
local toolbar.
- 253 -
MADCAP FLARE
c. Click OK.
- 254 -
Group selected items:
You can group topics in the same cell so that they function as a unit or are related to one
another. When you group items together, you can choose a collection type to specify how the
items within the group behave.
a. In a cell containing multiple items (topic references), hold your CTRL key and click
the items that you want to group.
. The word "Group" is added to the cell.
- 255 -
MADCAP FLARE
- 256 -
Select the collection type for a column or topic link item:
When you put items into a group, you can specify how that group will function as a collection (e.g., in the images above the group is using the "Family" collection type, which
means that those topic items will reference each other in the output). You can do this for
entire columns or for individual topic items in a cell that have been grouped. If you set a particular collection type on a column, all groups in that column will use that collection type.
a. Do one of the following:
n
For columns: Click in a column. In the local toolbar click
.
OR
n
For topic link items: Click on a topic link item in a cell. In the local toolbar
click .
b. Click in the Collection Type field and select one of the following:
n
Unordered (default) This displays the grouped links in the output, but the
order in which they are displayed is not important.
n
Family This lets you display links not only to adjacent topics in the row, but to
other topics grouped within the same cell as well.
E X AMPLE
Let 's say y ou hav e a row t hat is p op u lat ed like t his:
Top ic A is in t he "concep t " cell.
Top ics, B, C , and D are cont ained in a grou p in t he "t ask" cell.
Top ic E is in t he "reference" cell.
Su p p ose y ou DO NOT u se t he Family collect ion t y p e. In t hat case,
when a u ser op ens Top ic A, he will see links t o Top ics B, C , D, and
E. Howev er, when t he u ser op ens Top ic C , he will see links t o
Top ic A and Top ic E, bu t not t o Top ics B and D.
Now su p p ose y ou DO u se t he Family collect ion t y p e. In t hat case,
when a u ser op ens Top ic C , he will see links not only t o Top ics A
and E, bu t t o Top ics B and D as well.
n
Sequence This displays links with significance given to how the links are
ordered in the output. For Flare outputs other than DITA, this option is not supported. For more detailed information about DITA and the sequence option,
please refer to xml.coverpages.org/dita.html.
- 257 -
MADCAP FLARE
n
Choice This lets you specify which link should be "selected" or "highlighted"
from the group of links. For Flare outputs other than DITA, this option is not
supported. For more detailed information about DITA and the choice option,
please refer to xml.coverpages.org/dita.html.
n
Use CONREF Target This uses the conref attribute to pull content. The conref
attribute references an ID on content that can be reused. For Flare outputs other
than DITA, this option is not supported. For more detailed information about
DITA and the conref attribute, please refer to xml.coverpages.org/dita.html.
c. Click OK.
Nest items:
After you add items to a cell, you can nest them by using the left and right arrows. If an item
is above and to the left of other items, it becomes the parent; the child items are below and to
the right of the parent. When this occurs, the child items inherit the settings from the parent
item (e.g., link type).
a. Click on a topic link in a cell that you want to move.
b. In the local toolbar, click
to move it to the left, or click
to move it to the right.
Move items up or down:
If you have multiple topic items in a cell, they are displayed in the output in the order they
are shown. You can use the up and down buttons to change the order.
a. Click the topic item that you want to move.
to move the item up or
Delete a row:
a. Click in the row you want to delete.
.
Delete a column:
a. Click in the column you want to delete.
- 258 -
.
to move the item down.
Show or hide conditional indicators:
In a relationship table, condition tags are shown in the small squares next to topic file names.
This feature can be used to show or hide those squares.
n
.
to save your work.
Note: If there are any broken links in a relationship table, they will be identified by this icon
You can then open the properties for that item and fix the link.
.
- 259 -
MADCAP FLARE
Inserting R elationship Links Into Topics
You can insert a relationships proxy in the topics where you want links to appear in the output,
using the information contained in your relationship table(s).
How to insert a relationship link into a topic
2. Place your cursor where you want to insert the link (usually at the bottom of the topic).
3. Select Insert>Proxy>Insert Relationships Proxy. The Relationships Proxy dialog opens.
4. (Optional) In the field labeled Stylesheet class for proxy, you can select a class to affect
the look of the relationship link.
You might create and use a proxy style class, for example, if you want to use a border special
border above the relationship links in the output. If you do not select a class from this field,
the generated link will use the style settings from the parent <MadCap|relationshipsProxy>
style. You have the option of creating a class for this proxy style in the Stylesheet Editor. To
do this, select the MadCap|relationshipsProxy style and click Add Class to create a
class. The class will then be available from this field.
5. Click OK. The proxy is added to the topic.
to save your work.
A ssociating R elationship Tables W ith Targets
If you have created relationship tables in your project, you need to tell Flare which tables to use for
which targets.
How to associate relationship tables with targets
2. In the Target Editor, click the Relationship Table tab.
3. Click next to each relationship table that you want to use for that target so that it has a check
mark.
- 260 -
to save your work.
Shortcut Controls
A shortcut control launches a program or window in an application by passing Windows-based messages and parameters. For example, if a topic discusses a procedure that involves a specific dialog
window, you can provide a link that a user can click in the topic to open the dialog in the program.
Shortcut controls can make tasks easier for new users, and they can speed up complex procedures
for experienced users.
The following are limitations of shortcut controls:
n
A Shortcut control can be used only with HTML Help.
n
The CHM file must be located on a local or network drive. The file cannot be accessed through
HTTP.
n
The CHM file must be displayed in the Help Viewer. A Shortcut control does not work in a file
that is displayed in an Internet browser window.
How to insert a shortcut control into a topic
2. In the XML Editor, click in the topic where you want to insert the shortcut control.
3. Select Insert>Help Control>Shortcut Control.
The Insert Shortcut Control dialog opens.
4. Enter the appropriate information in each of the fields. You may need to consult with your
developer for help on completing these fields.
n
File path to the executable file… Enter the path and name of the program that
(EXE file) you are calling.
n
Parameters to be sent… Enter any parameters you would like to send the program
(e.g., the name of a file to open). Separate the parameters with commas.
n
A message ID of a standard Windows message Select a standard Windows message from the drop-down menu.
n
WPARAM value Enter the WPARAM value.
n
LPARAM value Enter the LPARAM value.
5. Click OK.
The Shortcut control is added to the topic.
to save your work.
Note: You can edit a shortcut control by changing its settings and by modifying its style. For
more information see the online Help or the Flare Styles Guide.
- 261 -
MADCAP FLARE
Breadcrumbs Proxy
If a breadcrumbs proxy is included in a master page, the output will display a "trail of breadcrumbs"
comprised of the table of contents (TOC) entries above the current topic in the TOC hierarchy.
To insert a proxy, open a master page, place your cursor where you want to insert the proxy, and
select Insert>Proxy>Insert Breadcrumbs Proxy. See "Creating Master Pages" on page 178.
- 262 -
- 263 -
MADCAP FLARE
H yperlinked B readcrumbs
If the books in the TOC are linked to topics in the project, the breadcrumbs will be hyperlinked in
the output; if the books are not linked in the TOC, the breadcrumbs will not be hyperlinked.
E X AMPLE
Here is a TOC where t he books are not linked t o t op ics.
- 264 -
Therefore, t he bread cru mbs in t he ou t p u t look like t his:
Here is a TOC where t he books are linked t o t op ics in t he p roject .
- 265 -
MADCAP FLARE
Therefore, t he bread cru mbs in t he ou t p u t look like t his:
How to link a TOC book to a topic
1. Open the TOC.
2. Select the TOC book.
3. In the local toolbar of the TOC Editor, click
. The Properties dialog opens.
4. Click Select Topic. The Link to Topic dialog opens, displaying all the topics in your project.
5. Select the topic to which you want to link the entry and click Open.
6. In the Properties dialog, click OK. The book is now linked to the topic.
to save your work.
Note: After you insert a breadcrumbs proxy into a master page, you can modify the look of the
breadcrumbs using styles. For more information see the online Help or the Flare Styles Guide.
- 266 -
Mini-TOCs
A mini-TOC proxy allows you to generate a portion of your table of contents (TOC) or topic headings
at a particular location in the output. A mini-TOC proxy can be used for both online and printbased output. For online output, you can insert a mini-TOC proxy into a master page. For printbased output formats, you can insert a mini-TOC proxy into any topic where you want to generate a
small TOC. For example, let's say you want the first page of each chapter in a manual to start out
with a small TOC, showing the page numbers where subheadings occur within that chapter. In that
case, you can insert a mini-TOC proxy into each topic that you plan to use as the beginning of each
chapter. If you insert the proxy into a master page, each topic using that master page will have a
mini-TOC. If you insert the proxy into certain topics only, mini-TOCs will be generated only within
those particular topics. For more information see the online Help or the Flare Printed Output
Guide.
How does Flare decide which topic links to include in a mini-TOC? It works just like a regular TOC
proxy that you can use for an entire manual. By default the mini-TOC for your print-based output is
based on the <h1> through <h6> tags that you have applied to content in your topics. When you
insert the proxy, you select a number for the heading depth. For example, if you place the proxy
after an <h1> heading and select 4 as the depth, the proxy will include headings that are using
<h2>, <h3>, and <h4> styles (but not <h5> or <h6>). Please note that the print TOC is NOT necessarily based on the structure of your "outline TOC." However, there is a switch on the Advanced
tab in the Target Editor that lets you base the generated mini-TOC on the structure of your "outline
TOC." Regardless of the method you choose, the links in the mini-TOC point to any topics that are
subordinate to the current topic.
E X AMPLE S
FO R
O N LIN E
OUT PUT
- 267 -
MADCAP FLARE
Here is how a mini-TOC might look in t he ou t p u t for a Help sy st em:
- 268 -
E X AMPLE S
FO R
PRIN T
-
B ASE D
OUT PUT
- 269 -
MADCAP FLARE
E X AMPLE
—
ST YLE S
ME T H OD
Let 's say t hat y ou want t o u se t he d efau lt met hod , where t he mini-TOC ent ries are
based on head ings u sing t he < h1> t hrou gh < h6 > st y les in y ou r p roject . Perhap s y ou
hav e creat ed a lengt hy t op ic, wit h t he < h1> st y le ap p lied t o t he first head ing in
t hat t op ic and sev eral su bhead ings below it t hat are u sing t he < h2> and < h3>
st y les. Like t his:
Now let 's say t hat y ou insert a mini-TOC p roxy bet ween t he < h1> head ing and t he
first < h2> head ing, like t his:
- 270 -
When y ou insert t he p roxy , let 's say y ou sp ecify t hat it shou ld u se a d ep t h of 3. In
t hat case, t he ou t p u t will d isp lay links t hat p oint t o all y ou r su bhead ings— t he
< h2> head ings (which are second - lev el head ings), as well as t he < h3> head ings
(which are t hird -lev el head ings). Bu t su p p ose y ou also hav e, say , < h4 > head ings in
t he t op ic cont ent . Those < h4 > head ings will not be inclu d ed in t he mini- TOC
because y ou select ed a d ep t h of 3 rat her t han 4 or higher.
In t he ou t p u t , it might look somet hing like t his:
- 271 -
MADCAP FLARE
E X AMPLE
—
T O C
ST RUCT URE
ME T H OD
Let 's say t hat y ou want t o u se t he met hod where t he mini-TOC ent ries are based on
t he st ruct u re of y ou r "ou t line TOC . " Perhap s y ou hav e creat ed sev eral t op ics t hat are
organized in y ou r TOC , like "C hap t er 5" in t his examp le:
That book in t he TOC consist s of sev en t op ics (C hap t er 5, Exercising a Dog, Ind oor
Exercise, Ou t d oor Exercise, Feed ing a Dog, Picking a Dog, and Training a Dog).
Let 's say t hat y ou want t o insert a mini- TOC p roxy int o t he "C hap t er 5" t op ic so
t hat it creat es a small TOC p oint ing t o t he ot her t op ics u nd er it . Fu rt hermore, sup p ose t hat y ou are u sing t he < h1> st y le at t he t op of each of t hose t op ics, and y ou
d o not want t o change t hat fact . In t hat case, y ou can simp ly insert t he mini- TOC
p roxy int o t he "C hap t er 5" t op ic, like t his:
- 272 -
When y ou insert t he p roxy , y ou sp ecify t hat it shou ld inclu d e t hree lev els of head ings in t he mini-TOC , becau se in t he ou t p u t Flare will creat e t hree lev els based on
y our st ruct u re.
You can t hen op en t he t arget t hat y ou want t o generat e, select t he Ad v anced t ab,
and click t he op t ion t o generat e y ou r TOC based on t he st ru ct u re of t he TOC in y our
p roject .
Like t his:
- 273 -
MADCAP FLARE
In t he ou t p u t , t he "C hap t er 5" t op ic might look somet hing like t his:
Please remember t hat t he t op ic cont aining y ou r mini-TOC p roxy mu st be on a higher
lev el in t he TOC t han t he t op ics t hat y ou want t o be cap t u red by t hat mini-TOC .
For steps on inserting and using mini-TOC proxies, see the online Help or the Flare Printed Output
Guide.
- 274 -
Page Layouts
A page layout is an element that you can create in your project in order to determine page specifications (e.g., size, margins) and to apply certain content (e.g., headers, footers, page numbers) to
many (or all) topics in print-based output. Page layouts allow for easy configuration through the use
of content frames, a snap-to grid, dragging and dropping, alignment features, and more. Page layouts are similar to master pages, but are more flexible and easier to use. The general rule of thumb is
that page layouts are recommended for print-based output (when possible), and master pages continue to be the best method for automatically adding headers, footers, and breadcrumbs in multiple
topics for online output. Another difference between page layouts and master pages is that page layouts can be used for any of the print-based outputs (Adobe PDF, XHTML, Microsoft XPS, Microsoft
Word, Adobe FrameMaker), whereas master pages can be used only for Microsoft Word and FrameMaker when creating print-based output.
E X AMPLE
Let 's say y ou are creat ing a manu al t hat consist s of front mat t er (e. g. , t it le p age,
cop y right p age, and t able of cont ent s), 10 chap t ers, and an ind ex. Perhap s y ou want
all of t he p ages in t he manu al t o measu re 8 inches in height and 6 inches in wid t h.
Furt hermore, y ou might want some p ages (e. g. , t it le and cop y right p ages) t o cont ain no head ers or foot ers, while y ou want t he ot her p art s of t he manu al t o cont ain
head er t ext and p age nu mbers at t he bot t om. In a sit u at ion su ch as t his, y ou might
creat e one p age lay ou t for y ou r t it le and cop y right p ages, a second p age lay ou t for
y our TOC , a t hird p age lay ou t t o be u sed by all of t he chap t ers, and a fou rt h p age
lay out t o be u sed by t he ind ex. Each p age lay ou t might cont ain t he same p age size
set t ings, bu t d ifferent p age head ers and foot ers.
Like all other files in Flare, a page layout is an XML file. It has an .flpgl extension and is stored in
the Content Explorer under the Resources\PageLayouts folder.
- 275 -
MADCAP FLARE
Multiple Pages In A Layout
Each page layout that you create can consist of one page or several pages. Why would you want
more than one page? If you want different content or settings to be applied to the various pages in
your final output—depending on their position in the document—you will want multiple pages. In
this way, page layouts are different from master pages, where you designate first, left, or right page
content on the same master page.
For each page in a page layout, you can designate one of the following types, which determines the
behavior of the page:
n
Normal Select this type if you do not want a right-left type of page flow, but instead just
want the same layout on every page, perhaps like a screenplay. Unlike "First," "Right," or
"Left," if you elect to begin a chapter with the "Normal" page, that page will be used throughout that chapter.
n
First Select this type if you want the settings to be applied to a page in the output when it
appears on the first page of a new chapter (or designated section).
n
Empty Select this type if you want the settings to be applied to an "empty" page in the output. When creating a printed manual, there may be times when you want a page in the document to purposely be left blank (or mostly blank). If you create an Empty page in a page
layout, it will automatically be used in the output if necessary, based on the page types in
your layout. For example, if you also have a Title page in the layout, the Empty page will be
inserted immediately after the title page in the output. Or let's say you have a First page type
in your layout, with the intention of using it to start each new chapter on a right page in the
output. If you also have an Empty page type in the layout, it will automatically be inserted
before the first page of a new chapter, if necessary, to ensure that it starts on a right (odd)
page. For more information see the online Help or the Flare Printed Output Guide.
n
Left Select this type if you want the settings to be applied to a page in the output when it
appears on a left (or even) page (e.g., page 42).
n
Right Select this type if you want the settings to be applied to a page in the output when it
appears on a right (or odd) page (e.g., page 43).
n
Title Select this type if you want the settings to be applied to the first page in your output,
which typically displays the manual title. If you include an Empty page in your page layout,
the title page in the output will immediately be followed by the empty page.
- 276 -
E X AMPLE
Let 's say t hat y ou are creat ing a p age lay ou t t o be u sed only for t he t it le p age t hat
occurs at t he v ery first p age of y ou r manu al. In t hat case, y ou r p age lay ou t might
hav e one p age t hat u ses t he Tit le p age t y p e. In ad d it ion, y ou can ad d an Emp t y
p age t y p e t o t hat lay ou t . In t he ou t p u t , t he Tit le p age will au t omat ically be followed by an emp t y p age.
Now let 's say t hat y ou are creat ing a second p age lay ou t t o be u sed for t he chap t ers
in y our d ocu ment . Su p p ose t hat on t he first p age of each chap t er, y ou d o not want
any head er, bu t y ou want a p age nu mber at t he bot t om-right of t he p age. Therefore,
y ou creat e one p age wit h a p age t y p e of First .
Next , su p p ose y ou want t he p ages t hat ap p ear on t he left sid e of t he d ocu ment t o
hav e t he name of t he manu al in t he u p p er- left corner and a p age nu mber in t he
lower-left corner. Therefore, y ou creat e anot her p age wit h a p age t y p e of Left .
Perhap s y ou want t he p ages t hat ap p ear on t he right sid e of t he d ocu ment t o hav e
t he chap t er name of t he manu al in t he u p p er-right corner and a p age nu mber in t he
lower-right corner. Therefore, y ou creat e anot her p age wit h a p age t y p e of Right .
Finally , let 's say y ou want t o ensu re t hat t he first p age of each chap t er st art s on t he
right sid e of t he manu al. In t hat case, y ou can creat e a fou rt h p age wit h a p age t y p e
of Emp t y . This allows an emp t y p age t o be forced (if necessary ) on t he left sid e
immed iat ely before t he beginning of t he next chap t er.
- 277 -
MADCAP FLARE
- 278 -
Frames
Each page in a layout can contain multiple frames, which are used to hold content (such as page
numbers and chapter titles) and determine where that content is positioned. By default, certain
frames will already be included in a page, depending on the template you select when adding a page
layout. Frames are typically displayed as large gray rectangles or squares on a page.
n
Body frame This frame, usually the largest on the page, is basically a placeholder for the
content that you add to topics. You cannot add content directly to a body frame. If necessary,
you can have multiple body frames on a page. This lets you customize the flow of text from
one frame to another on a page.
E X AMPLE
Let 's say y ou want t he bod y t ext be d isp lay ed in one colu mn on t he t op
quart er of each p age, bu t t hen y ou want t he t ext t o cont inu e below in t wo columns. In ord er t o accomp lish t his, y ou can creat e t wo bod y frames on a p age—
one wit h a single colu mn and t he ot her wit h t wo colu mns.
- 279 -
MADCAP FLARE
n
Header frame This frame is designed to hold content from the topic (e.g., chapter title,
page number) or text that you add. The frame is usually positioned at the top of a page,
above the body text.
n
Footer frame This frame is designed to hold content from the topic (e.g., chapter title, page
number) or text that you add. The frame is usually positioned at the bottom of a page, below
the body text.
n
Decoration frame This frame can be used to display a bar for aesthetic purposes on a page.
You can add color, a border, text, and images to a decoration frame.
Note: Decoration frames are not supported in Microsoft Word or Adobe FrameMaker output.
n
Image frame This frame opens the Insert Picture dialog, prompting you to provide an
image file. The picture is added to a frame of the same size, which you can place on the page
as necessary.
Note: Image frames are not supported in Microsoft Word or Adobe FrameMaker output.
To position frames on a page, you can simply click on the edge and drag to resize. You can also click
in the middle of a frame and drag to move it. In addition, there are various options available from
the Layout drop-down button for aligning and positioning frames, as well as for rotating text within
a frame.
Page Layout Templates
When you add a new page layout to your project, you select a page layout template as the basis for
the new layout. Flare lets you choose from various factory templates, each of which is useful for different circumstances. After adding a new page layout based on a template, you are free to change it
in any way you see fit.
- 280 -
Steps For Using Page Layouts
Following are the main steps necessary for creating and using page layouts. For information about
each, see the online Help or the Flare Printed Output Guide.
1. Add page layout After determining the number of page layouts that are needed to produce
the kind of output you want, you can add the page layout files to the project (select
Project>Add Page Layout). The best course of action is usually to use the factory templates provided by Flare and edit them as necessary. Another approach is to make copies of
finished page layouts. After you configure a page layout as needed (adding pages, frames,
page size settings, content), you can copy that page layout to create the additional ones that
you need. That way, much of the work may already be completed in the subsequent page layouts, with only some tweaking necessary.
2. Add pages In each page layout, you need to decide how many pages you will need and add
them to the layout. The number of pages that you add depends on the differences that may
occur on the various pages. For example, you might add a First page to be used only for the
first page of the chapter. You also might add a Left page for even pages (e.g., 12, 14, 16, 18)
and a Right page for odd pages (e.g., 11, 13, 15, 17). Each of those page types might display
header or footer content differently. You also might want to add an Empty page, which is useful for making sure that new chapters start on either a right or left page. In the Page Layout
Editor, only one page will be visible at any one time, but you can navigate to the other pages
quickly by using the small squares to the right of the editor (one for each page in the page layout).
3. Add or remove frames Each page in a layout can contain multiple frames, which are used
to hold content (such as page numbers and chapter titles) and determine where that content
is positioned. By default, certain frames will already be included in a page, depending on the
template you select when adding a page layout. Frames are typically displayed as large gray
rectangles or squares on a page. You can add more frames or remove existing frames as necessary.
4. Edit pages and frames After you have the pages and frames that you need in a page layout, you can modify them to affect the content, as well as the look of the pages in the output.
This might consist of various tasks, such as inserting page numbers or text, adding borders to
frames, resizing frames, and more.
- 281 -
MADCAP FLARE
5. Specify chapter break and page layout After you create a page layout and configure its
frames and settings as necessary, you need to associate the page layout with the appropriate
content. In most cases, you will probably want to associate different page layouts with various entries in your "outline TOC" (so that different page layouts can be used for different
parts or "chapters" in a manual). Otherwise, you would associate a single "master" page layout with an entire target or project; in that case, the same page layout will be applied to all
topics in that target or project. Whenever you associate a page layout with a TOC entry, you
must first create a chapter break in order to do so.
n
Associate page layout with outline TOC entry If you want different parts of a
manual to use different page layouts (e.g., one layout for the front matter, another for
chapters, another for the index), you would associate the appropriate page layouts
with the outline TOC entries where you want those page layouts to start.
OR
n
Associate page layout with target and/or project If you want a page layout to
be applied to all topics in the output or project, you would associate that page layout
with the target that you are building or with the entire project.
Note: In order to apply styles to content that you add in a page layout, you need to apply a
master style sheet at either the target or project level. Style sheets cannot be applied to individual page layouts (as they can with topics). For more information see the online Help or the Flare
Styles Guide.
- 282 -
Pictures
You can insert a picture into a content file (e.g., topic, snippet) to help explain something. Flare
supports the following types of raster and vector image files: BMP, EMF, EPS, EXPS, GIF, HDP,
JPG, JPEG, PNG, PS, SVG, SWF, TIF, TIFF, WDP, WMF, XAML, XPS.
Raster Versus Vector Images
Flare supports common raster image formats such as BMP, GIF, JPG, and PNG. In addition, it supports vector image formats such as EPS, PS, and SVG.
A vector image is comprised of geometric elements such as lines, points, and curves, based on mathematical equations. On the other hand, raster graphics are made up of pixels. A vector image is ideal
for print- based output because the clarity is maintained even when you reduce the size of the
graphic. If you generate an online output type such as WebHelp or DotNet Help, all vector images
are converted to PNG.
It is sometimes difficult to tell the difference between a vector and raster graphic when viewing it at
100%. But if you zoom in the difference becomes apparent. Following is an example of a PDF document with the same image in JPEG and SVG format.
- 283 -
MADCAP FLARE
The text in the SVG image is a little more readable. And if we zoom in, we can see why.
- 284 -
Here is what the JPEG image looks like when we zoom in at 300%. Notice that the pixels look blurry
when enlarged.
- 285 -
MADCAP FLARE
And here is what the SVG image looks like. Notice that the text still looks as clear as it does at a
much smaller size.
- 286 -
Tasks Associated With Pictures
You can accomplish the following with pictures.
n
Picture (insert) These steps show you how to insert an image file that already exists. See
"Inserting Pictures" on page 290.
n
Screen capture (insert) Follow these steps if you have MadCap Capture installed on your
computer and you want to capture an image from your screen and insert it into a topic at the
same time. See "Inserting Screen Capture Images into Topics" on page 294.
n
Single-source image (create) If you are creating a project containing pictures and need
to generate output for both online and printed output, chances are good that you require different image settings (e.g., file format, color depth, resolution) for those outputs. In the past,
the easiest way to accomplish this task was to create one set of images for the online output
and another set for the printed output. However, there is another alternative. If you have both
MadCap Flare and MadCap Capture installed, you can single-source your images, producing
only one set of images for all outputs. You can specify that the online images should have one
group of settings, while the printed images have another group of settings. See the online
Help.
You can also single-source images when resizing them. This can be done through the use of
styles (applying the settings to many images at once) or local formatting (applying the settings to one image). When you generate online output, the image will be displayed in one
size, and when you generate print-based output, the image will be displayed in another size.
n
Background (add) You can add background settings to an image. This includes the ability
to specify a color, another image, and a repeating pattern for the background image. Normally
you would not see an image's background, but if you give the image a certain amount of padding, you would see the background around the edges of it. See the online Help.
n
Background for topics (add) You can add a background image on topics by using the
<body> style tag. See the online Help.
n
Borders (add) You can add borders around an image, specifying the border size, color, and
type. See the online Help.
n
Hyperlink (insert) After you insert a picture into a topic, you can turn that picture into a
hyperlink, connecting it to another topic, a topic in an imported HTML Help file, an external
file (such as a website), or an email. See "Image Hyperlinks" on page 219.
n
Image file (add) These steps show you how to add a picture to your project, without inserting it into a topic. See the online Help.
n
Image file (delete) These steps show you how to remove an image file from a project. See
the online Help.
n
Image frame (add) You can draw an image frame in a page layout. The picture you select
is added to a frame of the same size, which you can place on the page as necessary. This
allows you to place an image automatically on multiple pages in the output. You might use
this feature, for example, if you want to place your company logo somewhere on each page.
See the online Help.
- 287 -
MADCAP FLARE
n
List of pictures (create) You can use the list-of proxy to generate a list of various types of
elements (e.g., tables, images) in your output, with links to the corresponding content. For
more information see the online Help or the Flare Printed Output Guide.
n
MadCap Capture (launch) If you have MadCap Capture installed on your computer, you
can launch it from within Flare. You can then use Capture to edit any pictures in your
project. See the online Help.
n
Margins (add) You can adjust the margins around an image so that there is extra space
above, below, to the right, or to the left of it. See the online Help.
n
Padding (add) You can add padding (i.e., extra space) between an image's border and the
image itself. See the online Help.
n
Picture (delete) These steps show you how to delete a picture that you have previously
inserted into a topic. See the online Help.
n
Picture (edit) If you have MadCap Capture installed on your computer, you can open any
image in your project. The image opens in Capture, where you can make changes to it. See the
online Help.
n
Picture (move) After you insert a picture or screen capture image into a topic, you can
easily move that picture around. See the online Help.
n
Picture (open) You can open a picture that you have added to your project. When you open
the picture, it displays in the Image Viewer within Flare. See the online Help.
n
Picture (position) You can use object positioning to precisely place an inserted picture anywhere you need it on a page. This includes the ability to wrap text around an image or float a
picture outside the frame holding the regular flow of text. See "Object Positioning" on page
400.
n
Picture (resize) You can resize images with various methods. See the online Help.
n
Thumbnails (show in output) When you insert images into Flare content, you can specify
that the pictures should be displayed as thumbnails (i.e., much smaller versions of the
image) in the output. This is a way to condense topics so that pictures are not taking up as
much real estate. When you use this feature, you can specify ways that the user can enlarge
the image to see its full size (e.g., by hovering over the thumbnail, by clicking the thumbnail).
See the online Help.
n
Thumbnails (show while editing) You can specify that thumbnail images should be
shown while you are editing the content. This is simply a feature for you as the author, allowing you to scale all images down to 48 pixels high (if the original size is larger than that).
This lets you see more content and less of your images as you edit topics. The images are only
scaled for your editing purposes; they are not shown as thumbnails in the output. See the
online Help.
Note: When you insert a picture from outside your project into a topic, a copy of the image file
is added to your project. The image file is stored in the Resources\Images folder of the Content
Explorer, unless you specify another location.
- 288 -
Note: If you have used non–web-safe image formats (e.g., WMF, EMF, BMP, TIF, TIFF, XPS,
EXPS) in your project and want those images to be converted to web-safe formats (e.g., GIF,
JPEG, PNG) when you generate online output (e.g., DotNet Help, HTML Help, WebHelp, WebHelp Plus, WebHelp AIR, WebHelp Mobile), you can use an option on the Advanced tab of the
Target Editor. For print-based output types (Adobe PDF, XHTML, Microsoft XPS, Microsoft
Word, Adobe FrameMaker), the original image file formats will be used when you generate output.
- 289 -
MADCAP FLARE
Inserting Pictures
The following steps show you how to insert a picture into a content file (e.g., topic, snippet), adding the image file to the project as well.
How to insert a picture
2. In the XML Editor place your cursor where you want to insert the picture.
n
Select Insert>Picture.
OR
n
Press CTRL+G on your keyboard.
OR
n
In the local toolbar of the XML Editor, click
.
5. Select an image file to insert. You can do this in various ways.
You can select an image file already in the project by finding and choosing it in the Select File
structure, etc.
You can click
to find and select an image file outside of the project.
If you want to select an image file that you recently inserted somewhere in your project, click
- 290 -
E X AMPLE
When y ou insert an image, t he d ialog might look somet hing like t his:
Note: If you select an image outside the project, that file is then copied and placed inside
the project. The image file is stored in the Resources\Images folder of the Content
Explorer.
6. (Optional) If you want to apply a specific style class to the image, you can select it from the
Style Class field.
E X AMPLE
Let 's say t hat y ou hav e creat ed in y ou r st y le sheet a class of t he < img> t ag
called "bu t t on" (i. e. , img. bu t t on) and y ou hav e set a maximu m size on t hat
st y le class. The id ea is t hat y ou want t o u se t hat st y le class whenev er y ou
- 291 -
MADCAP FLARE
insert an image of a bu t t on, ensu ring t hat t he image alway s d isp lay s in a v ery
small size. Rat her t han u sing t he d efau lt p arent < img> t ag when y ou insert
t he image, y ou select img. bu t t on from t he St y le C lass d rop -d own.
hovers over the picture.
8. (Optional) In the Alternate Text field you can type alternate text to display when the image
is not available, such as when a disabled individual is using a screen reader.
9. Select Apply the alternate text and screen tip to all image references if you want
the same alternate and screen tip text to be used everywhere the image is used in the project.
10. (Optional) Use any of the other tabs to provide additional settings for the image.
- 292 -
n
Size and Print Size tabs You can use these tabs to resize the image. If you want to
provide only one group of settings for the image, use the Size tab. If you want to provide two groups of settings—one for online output and another for print-based output—
use the Size tab for online output, then use the Print Size tab for print-based output.
n
Position tab You can use this tab to adjust the positioning of the image on the page.
This includes the ability to wrap text around an image or float a picture outside the
frame holding the regular flow of text.
n
Thumbnail tab You can use this tab to create a thumbnail version of the image in
the output.
n
Borders & Margins tab You can use this tab to set borders, margins, or padding for
the image.
n
Background tab You can use this tab to add background settings (e.g., color, image)
for the picture.
11. Click OK.
The picture is added.
to save your work.
- 293 -
MADCAP FLARE
Inserting Screen Capture Images Into Topics
If you have MadCap Capture installed on your computer, you can use it to capture an image from
your screen and insert it into a topic at the same time.
How to insert a screen capture into a topic
2. In the XML Editor, place your cursor where you want to insert the picture.
3. Select Insert>Screen Capture. The Screen Capture dialog opens.
4. Complete the appropriate setup fields in the dialog:
n
File name Enter a name for the image that you are capturing, or you can use the
default name provided.
n
Folder Select the folder where you want the captured image to be stored in the Content Explorer. n
Profile or Format Select the profile or file format that you would like to use when
capturing the image. A profile (created in MadCap Capture) lets you capture the image
with many additional settings applied to the image in advance.
n
Launch MadCap Capture Editor Select this check box if you want MadCap Capture to be launched when you capture an image. The image will be displayed in MadCap Capture. This is a useful option if you want to edit the image (e.g., add callouts,
lines, borders) after you capture it. When you edit and save the image in Capture, the
changes will automatically be reflected in Flare.
5. Select the capture option that you want to use, and complete the steps for each one as necessary:
n
Capture UI Element Captures a fixed area of a window (e.g., menu bar, toolbar,
editor, individual button, entire window), depending on where you move your mouse
and click. As you move the mouse in an application, a red border surrounds each separate region.
n
Capture Application Captures an open application. When you click this button, the
Select window opens, displaying a list of all open applications. You can select the application that you want to capture.
n
Capture Region Captures a rectangular region of your computer screen. When you
click this button, a rectangle with a red border displays over your screen. You can move
and resize this rectangle by clicking and dragging the small squares around the red border. Click the OK button near the rectangle to capture the region. This option is useful,
for example, if you want to capture only a portion of a toolbar or a specific area of a
window, but not the entire window.
- 294 -
to save your work.
QR Code
You can insert a QR code into a content file (e.g., topic, snippet) using the XML Editor. A QR code
is a type of barcode that can be read by devices such as smart phones. The data encoded in the
QR Code can be text, a website URL, an email address, contact information, or SMS (Short Message
Service, which is used for sending text messages). Basically, QR codes are a way to bridge the gap
between a static print document and searchable, more detailed online information at your fingertips.
There are many different kinds of QR code readers on the market. If you have a mobile device that
supports QR code readers, you can install an app and use it to read these types of codes.
E X AMPLE
Here is an examp le of a QR cod e:
If y ou hav e a QR cod e read er on y ou r cell p hone, y ou can scan t his QR cod e and t he
Mad C ap Soft ware websit e will op en on y ou r screen.
Following are some possible uses for QR codes.
n
You create a PDF manual that includes links directing users to your company's website. But
you want users to be able to quickly open those links without having to type in the entire
URL. So instead of regular hyperlinks, in your PDF you use QR codes.
n
You create a quick start guide and are limited to a couple pages. At the bottom of each page,
step, or procedure, there is a QR code that people can use to access more detailed information
on that topic.
n
You publish your entire Help system on a website. You have users who need access to that
information when they are "out in the field." So they scan a QR code that opens the URL
where your Help system is published.
n
You have a procedures manual with QR codes that, when scanned, open movies showing the
procedures in action.
n
You have a QR code at the bottom of a document takes users straight to a website where they
can purchase a particular part or product.
- 295 -
MADCAP FLARE
Inserting QR Codes
You can insert a QR code in much the same way you insert an image into a content file (e.g., topic,
snippet).
How to insert a QR code
2. In the XML Editor place your cursor where you want to insert the QR code.
n
Select Insert>QR Code.
OR
n
On your keyboard press CTRL+Q.
The Insert QR Code dialog opens.
5. From the Content type field, select one of the following options:
n
n
n
- 296 -
Text Select this if you want a simple text message to display on the end user's screen.
After selecting this option, complete the following:
o
Content Type the short text message that you want users to see after they scan
the QR code.
o
Size Select or one of the basic sizes for the QR code. If you select (default), the
code will be the size specified in the <MadCap|qrCode> style in your style sheet.
If you want to use a different size, you can set the max-height or max-width
value for the <MadCap|qrCode> style tag.
URL Select this if you want a web page to open in the end user's browser. After selecting this option, complete the following:
o
Content Type the website path (e.g., http://mycompany.com).
o
Email Address Select this if you want a particular email address to display on the
end user's screen. The end user might then copy the address to the clipboard and paste
it into an email. After selecting this option, complete the following.
o
Content Type the email address after the text "mailto:" (e.g.,
to:[email protected]).
mail-
o
n
n
Contact Information Select this if you want contact information for an individual to
display on the end user's screen. The end user might then create a new contact based
on that information. After selecting this option, complete the following:
o
Name Type the full name of the individual.
o
Company Type the company name.
o
Phone number Type the phone number.
o
Email Type the email address for the individual.
o
Address Type the physical address.
o
Website Type the website (e.g., http://mycompany.com).
o
Memo Type any other relevant information.
o
SMS Select this if you want to create an SMS (Short Message Service) message. After
scanning the QR code, the end user will be able to quickly send a text message to the
specified phone number. After selecting this option, complete the following:
o
Phone number Type the phone number where the text message is to be sent.
o
Message Type the text message.
o
6. (Optional) If you want to apply a specific style class to the QR code, you can select it from
the Style Class field.
E X AMPLE
Let 's say t hat y ou hav e creat ed in y ou r st y le sheet a class of t he < Mad C ap |qrC od e> t ag called "Red Bord er" (i. e. , Mad C ap |qrC od e. Red Bord er) and y ou
hav e set a red bord er on t hat st y le class. So if y ou want a QR cod e t o hav e a
red bord er, y ou can u se t hat st y le class when insert ing t he QR cod e. If y ou d o
not want t he QR cod e t o hav e a red bord er, y ou can simp ly u se t he d efau lt p arent < Mad C ap |qrC od e> t ag inst ead .
hovers over the QR code.
8. (Optional) In the Alternate Text field you can type alternate text to display when the QR
- 297 -
MADCAP FLARE
code is not available, such as when a disabled individual is using a screen reader.
9. (Optional) Use any of the other tabs to provide additional settings for the QR code.
n
Position tab You can use this tab to adjust the positioning of the QR code on the
page. This includes the ability to wrap text around a QR code or float a QR code outside the frame holding the regular flow of text.
n
Borders & Margins tab You can use this tab to set borders, margins, or padding for
the QR code.
n
Background tab You can use this tab to add background settings for the QR code.
This includes the ability to specify a color, image, and a repeating pattern for the background image. Normally you would not see a QR code's background, but if you give the
QR code a certain amount of padding, you would see the background around the edges
of it.
10. Click OK.
The QR code is inserted.
- 298 -
to save your work.
Rulers
A ruler is a horizontal line (or bar) that you can insert into a topic. You might use a ruler, for example, as a design element to separate your topic title from the content.
Flare provides the <hr> style tag, which you select when inserting a ruler. If you want, you can
change the way a ruler looks (size, color, etc.) by editing the <hr> style properties in the Stylesheet
Editor.
How to insert a ruler into a topic
2. In the XML Editor, place your cursor where you want to insert the ruler.
3. Select Insert>Ruler.
The Insert Ruler dialog opens.
4. Select hr.
to save your work.
Note: After you insert a ruler ("horizontal line") in a topic, you can edit its settings (e.g., size,
color, position) by modifying the <hr> style in the Stylesheet Editor. For more information see
the online Help or the Flare Styles Guide.
- 299 -
MADCAP FLARE
Scripts
If you are experienced with using JavaScript, VBScript, or JScript, you can insert such scripts into
your topics. If you can create a script that can be used in a website, you can create it in Flare as
well.
n
JavaScript This is a scripting language that lets authors design interactive sites. It shares
many of the features and structures of the full Java language, but was developed independently. JavaScript can interact with HTML source code, enabling authors to include
dynamic content in their sites.
n
JScript This is Microsoft's extended implementation of ECMAScript (ECMA262), an international standard based on Netscape's JavaScript and Microsoft's JScript languages. JScript
is implemented as a Windows Script engine. This means that it can be "plugged in" to any
application that supports Windows Script, such as Internet Explorer, Active Server Pages,
and Windows Script Host. It also means that any application supporting Windows Script can
use multiple languages—JScript, VBScript, Perl, and others. JScript (and the other languages)
can be used for both simple tasks (such as mouseovers on web pages) and for more complex
tasks (such as updating a database with ASP or running logon scripts for Windows NT). Windows Script relies on external "object models" to carry out much of its work. For example,
Internet Explorer's DOM provides objects such as "document" and methods such as "write()"
to enable the scripting of web pages.
n
VBScript This is a scripting language based on MS Visual Basic and, like JavaScript, is
embedded in a web page. The interpretation and execution of scripts is controlled by the Web
client. Much like JavaScript, functions are most often executed by mouse functions, navigation buttons, Active X controls or by actions initiated by the user or by automated scripting
such as retrieving user computer information.
- 300 -
How to insert a script into a topic
2. In the XML Editor, place your cursor where you want to insert the script.
3. Select Insert>Script. The Insert Script dialog opens.
4. From the Language drop-down menu, select text/javascript, text/jscript, or
text/vbscript.
n
In the Script Code area, type the code for the script.
OR
n
Next to the Script Link field, click the Browse button to find and select a script file.
6. Click OK. The script is added to the topic, with the script icon displayed at the spot of the
insertion.
to save your work.
- 301 -
MADCAP FLARE
Search
You can add the search feature to any of your online output targets. When users want to find information about a specific subject, they enter key words in the Search field. A search engine looks
through every topic in your project to find the term(s) entered by the user. When it finds the terms,
it presents the user with a list of topics to open. Search results are ranked, not listed alphabetically.
The search feature is good because it is very thorough. However, it also might return several topics
that contain the search terms but are not really relevant for the user's needs. That is why creating an
index is also important.
Steps For Using Search
Following are the basic steps for adding the search feature for your end users:
1. Enable search To include the search feature in your output, simply enable it in the skin
you want to use for the target. See "Enabling Search in Skins" on page 306.
2. Associate skin with target Now that the search feature is enabled in the skin, you need to
associate that skin with the target you are building. See "Associating Skins with Targets" on
page 412.
3. (Optional) Add search filter A search filter lets users narrow their search based on concepts. Concepts are simply keyword markers that you insert into topics that have some kind
of relationship with each other. They are also used for inserting concept links into topics. For
4. (Optional) Modify styles for highlighted search terms When users perform searches
in your online output, the keywords that are found are highlighted in the topics. The background for each term found in a topic is highlighted in a different color. In Flare you can
create styles for this purpose and change not only the color background, but other settings as
well (e.g., font style, text decoration). See the online Help.
5. (Optional) Include or exclude topics from search You can include a particular topic
in the generated output but exclude it from any search that users perform. See the online
Help.
6. (Optional) Include stop words in search Flare has a "stop words" list behind the scenes
that omits certain common words (such as "an" and "the") when users perform searches. However, if you would like those common words to be included in user searches, you can easily do
so. See the online Help.
Note: If end users want to find a specific combination of words that are always next to each
other in the same order (e.g., content management system), they can enter the search keywords
within quotation marks (e.g., "content management system").
Note: Wildcard searches are supported in DotNet Help output only.
- 302 -
Server-Side Search
Following are some additional features of search that may be available to you. Some of these features
are available if you integrate your project with MadCap Feedback, and others are available if you use
the WebHelp Plus output:
Features A vailable W ith MadC ap Feedback
n
Reports on search keywords With MadCap Feedback, you can determine how readers are
using search in your online output. This helps you answer questions such as: What are they
looking for? What are they finding? And more importantly, what are they unable to find? You
can use Feedback Explorer to view all used search phrases, as well as searches where no
results were returned to the user.
n
Creating synonyms If users enter search phrases in your online output and those phrases
are not returning results, this does not need to be the end of the story. You can make improvements to your output so that, in the future, users are able to find the search results they need.
One way to make an enhancement is to add the information that your users are looking for (if
that information does not yet exist in your Flare project). Another way to enhance your output is to create synonyms for search phrases.
You can create synonyms within the Flare project or within Feedback Explorer (which is used
with MadCap Feedback). It is not mandatory that you have MadCap Feedback in order to use
synonyms in Flare output, but using MadCap Feedback makes it much easier to determine
which words require synonyms based on the search results of your users. Using Feedback
Explorer to create synonyms is appealing because the synonyms become immediately available for users searching in your output (without needing to republish the output). Be aware,
however, that creating synonyms in Feedback Explorer works for the Feedback output as long
as you continue to publish output to the same server. If you create synonyms in Feedback
Explorer, it is recommended that you also create those synonyms at the source (i.e., within
the Flare project), in case you ever publish to a different server. The easiest way to do this is
to export the synonym file from Feedback Explorer to the Project\Advanced folder in the Flare
project. See Feedback Explorer online Help for more information and steps on how to export
synonym files.
Note: After you create synonyms, there is nothing else you need to do in order to make
them available in the output. If you create synonyms in Flare, they are automatically
applied at the project level, so all targets will incorporate those synonyms when you generate and publish the new Flare output. If you also have MadCap Feedback and create the
synonyms in Feedback Explorer instead, the synonyms become immediately incorporated
into the output (even if you do not republish your Flare target). Please note that if you are
testing synonyms in Feedback Explorer, you may need to refresh the interface to see the
changes
For more information about performing this task in Flare, see "Creating Synonyms to
Enhance Search Results" on page 307. For more information about performing this task in
Feedback Explorer, see the online Help provided with that application.
For more information about MadCap Feedback, see the online Help.
- 303 -
MADCAP FLARE
Features A vailable W ith W ebH elp Plus
n
Searching non-XHTML files When end users perform a search in your online output, you
can ensure that non-XHTML files (e.g. PDF, DOC, XLS) are included in that search. This is
possible if you have installed it on a Web server running Microsoft IIS and published WebHelp Plus output to that server. When you build WebHelp Plus output, a subfolder named
"AutoSearch" is created and placed in the generated output folder. You can place non-XHTML
files within the published AutoSearch subfolder (whether the non-XHTML files are linked to
content from your Flare project or not). When users perform a search in your output, those
non-XHTML files will also be scanned and become accessible to the users.
n
Faster searching Another benefit of generating and publishing WebHelp Plus output to a
Web server running Microsoft IIS is that users will find the task of performing a search to be
much faster than it is otherwise. This is especially useful if you have a very large Help system.
Note: If you are generating WebHelp Mobile output, please note that search is not supported in
Palm operating systems.
Note: If you have problems with search working in HTML Help output, you might need to register a dll file called "RegisterItcc.bat." This may occur if you previously had a program such as
RoboHelp installed and then uninstalled it. As a result, the dll file was unregistered. Following
are the necessary steps for registering the dll file, depending on whether you are working in 32bit or 64-bit.
To register the dll in Windows:
In Windows Explorer find and double-click the following file:
C:\Program Files\MadCap Software\MadCap Flare V7\Flare.app\Resources\Bin\RegisterItcc.bat
To register the dll in 32-bit Windows 7:
1. In Windows Explorer navigate to the Resources/Bin folder where you installed Flare (e.g.,
C:\Program Files\MadCap Software\MadCap Flare V7\Flare.app\Resources\Bin).
2. Right-click on RegisterItcc.bat and select the option to run it as an administrator.
- 304 -
To register the dll in 64-bit Windows 7:
1. In Windows Explorer navigate to C:\WINDOWS\system32.
2. Right-click on the file cmd.exe and select the option to run it as an administrator. The command prompt window opens.
3. At the command prompt, type the following and press Enter:
"C:\Program Files (x86)\MadCap Software\MadCap Flare V7\Flare.app\Resources\bin"
4. Type RegisterItcc.bat and press Enter.
5. Close the command prompt window.
- 305 -
MADCAP FLARE
Enabling Search In Skins
The first step in making search accessible in your online Help is to enable the feature in the skin that
you want to use for your output target.
How to enable search in a skin
1. From the Project Organizer, open the skin.
2. On the General tab, click the Search check box.
3. (Optional) If you are creating HTML Help, you can include advanced search options. To do
this, select the HTML Help Setup tab and select Show Advanced Search. This includes
options for searching previous results, matching similar words, and searching titles only.
to save your work.
Note: If you are generating WebHelp Mobile output, please note that search is not supported in
Palm operating systems.
- 306 -
Creating Synonyms To Enhance Search Results
You can make improvements to your output so that, in the future, users are able to find the search
results they need. One way to enhance your output is to create synonyms for search phrases. This
way, even if a user enters a search term that is not included anywhere in the project, that person
will still be able to find the appropriate information.
How to create synonyms
1. Do one of the following to create or open a synonym file.
Create a synonym file:
a. If you have not done so already, add a synonym file to the project. Start by selecting
Project>Advanced>Add Synonym File.
b. Enter a name for the synonym file and click Add.
c. In the Copy to Project dialog, click OK.
OR
Open a synonym file:
a. Make sure the Project Organizer is open.
b. Double-click the Advanced folder.
c. Double-click the synonym file.
2. In the Synonyms Editor, you can create either directional synonyms, or you can create synonym groups.
Directional synonym This is a synonym that works in one direction (Word—>Synonym). It
is a useful method if readers enter a search term that is not contained in your project, but you
have a similar word that is contained in the project. It works like this… In the Synonyms
Editor, you enter the word that is not producing search results (because it is NOT contained
in your project content). Next to it, you enter a synonym—a word that will produce search
results (because it IS contained in your project content). When users enter the original word
again in future searches, topics containing the synonym are found.
E X AMPLE
Let 's say t hat y ou u se Mad C ap Feed back t o v iew search key word resu lt s from
y ou r u sers and find t hat many are ent ering t he search t erm "sofa. " Unfort unat ely , y ou hav e not u sed t hat word in y ou r p roject , so u sers are u nable t o
find t he t op ics t hat t hey need . Howev er, y ou hav e u sed a similar word ,
"cou ch. " Therefore, in t he Sy nony ms Ed it or, y ou ent er "cou ch" as a sy nony m
for "sofa. " The next t ime a read er ent ers "sofa" as a search key word , t op ics cont aining t he word "cou ch" will be ret u rned in t he resu lt s.
a. Select the Directional tab.
b. Click in the empty Word cell and press F2 on your keyboard.
- 307 -
MADCAP FLARE
c. Type the phrase that does not produce search results (e.g., sofa). Press Enter.
d. Click in the empty Synonym cell and press F2 on your keyboard.
e. Type the parallel search phrase that is contained in the project content (e.g., couch).
Press Enter when you are finished. In the future, when users perform a search and
enter the term from the Word cell (e.g., sofa), Flare will find all topics that contain the
term that you entered in the Synonym cell (e.g., couch).
f. (Optional) Click in the Stem check box if you want Flare to accept other variations of
the search term that have the same stem.
E X AMPLE
Let 's say y ou ent er "hike" in t he Word cell, and y ou ent er "walk" in t he
Sy nony m cell. Then y ou select t he St em check box. In t he fu t u re, if u sers
search for t he word "hike, " it will find all t op ics cont aining t he word
"walk. " The same will hap p en if u sers ent er ot her search p hrases wit h
t he same st em, su ch as "hiked " or "hiking. "
Synonym group This is a collection of synonyms that produces the same search results for
all of the words in the group. It is a useful method if you have multiple terms in your project
that are similar, and you want the same search results to be returned when users enter any of
those phrases. In the Synonyms Editor, you enter the terms with an equal sign between each
one (Synonym1=Synonym2=Synonym3). When users enter any of those terms in future
searches, all topics containing any of those words are found.
E X AMPLE
Let 's say t hat y ou hav e writ t en some cont ent abou t sp ort s, and many of y our
t op ics inclu d e t he word s "sp ort s, " "at hlet ics, " or "games. " If a u ser ent ers t he
word "at hlet ics" as t he search t erm, it will ret u rn not only t op ics cont aining
t hat word , bu t also t op ics cont aining t he word s "sp ort s" or "games" (ev en if
"at hlet ics" d oes not occu r in t hose ot her t op ics).
a. Select the Groups tab.
b. Click in the empty Group cell and press F2 on your keyboard.
c. Type the words that you want to include in the group, with an equal sign between each
(e.g., sports=athletics=games). Press Enter when you are finished.
- 308 -
d. (Optional) Click in the Stem check box if you want Flare to find other variations of the
synonyms that have the same stems.
E X AMPLE
Let 's say y ou ent er "hike= walk" in t he Grou p cell. Then y ou select t he
St em check box. In t he fu t u re, if u sers search for t he word "hike, " it will
find all t op ics cont aining t he word s "hike" or "walk. " Howev er, it will
also find t op ics cont aining word s t hat hav e t he same st em as t hose
t erms, su ch as "hiked , " "hiking, " or "walking. "
to save your work.
Note: If you merge projects, synonym files will remain separate in each project. For example, if
you create synonyms in Project A but not in project B, only the topics from Project A will use the
synonyms when users perform searches in the output.
- 309 -
MADCAP FLARE
Flare supports integration with Microsoft SharePoint. If your company uses Microsoft SharePoint
(software that allows organizations to collaborate, share files, and publish information to the Web),
you can connect to a SharePoint server. Doing this makes it easy to access and edit the SharePoint
files from any of your Flare projects. You can even copy SharePoint files to your project with mappings that let you keep them synchronized with the source files. In addition, you can publish Flare
output to a SharePoint server. Finally, you can use the SharePoint server to store any kind of template files supported in Flare so that they can be used by any Flare users in your company.
SharePoint is like a scaled-down version of a source control tool, with the ability to check out and
check in files. Many organizations use a source control tool to manage files that are part of products
and will be shipped to customers, while using SharePoint mostly for internal files to be shared
among colleagues.
E X AMPLE
Let 's say y ou need sev eral p eop le— su ch as su bject mat t er exp ert s, managers, or
p eers—t o rev iew y ou r t op ics. You can alway s email rev iew p ackages t o t hose ind iv id uals, but an alt ernat iv e is t o u p load t he rev iew p ackage t o a SharePoint serv er. Each
rev iewer can check ou t t he p ackage, make t heir comment s, and check t he file back
in. You can t hen bring t he rev iew p ackage back int o y ou r p roject , int egrat ing t he
up d at ed t op ics int o y ou r p roject .
- 310 -
Steps For U sing SharePoint Integration
Following are steps that you can perform when it comes to SharePoint integration. Connecting to
the SharePoint server is the only mandatory step. The other steps are optional, depending on how
you and your company or team wants to work. You might decide to use the check-in/check-out functionality, or you might decide to use the copy/map/synchronize features.
1. Connect to SharePoint server From the SharePoint Explorer in Flare, you can connect to
a specific SharePoint server. You can then use that window pane to access the files on that
server. See "Connecting to a SharePoint Server" on page 313.
2. (Option #1) Open/edit the actual SharePoint files If you want to open and edit any of
the files existing on the SharePoint server, you can do so with or without checking them out.
It all depends on how your company or team likes to work. If it is decided that individuals
working on SharePoint files should check them out first, follow all three steps below. Otherwise, you can simply perform the middle step to simply open and edit the files.
a. (Optional) Check out files You can check out files from the Flare interface. Checking out a file simply means to activate a "flag" on the SharePoint site indicating that
you want to access the file and prevent others from editing it and conflicting with your
changes. See "Checking Out SharePoint Files" on page 316.
If necessary, you can also undo any check outs.
b. Open and edit files You can open a file from the SharePoint Explorer by simply double-clicking it. When you do this, you are opening the actual file existing on the SharePoint site. If it is a file type not supported in Flare, you will be directed to open the file
in its default application. See "Opening SharePoint Files" on page 314.
c. (Optional) Check in files When you are finished working on a SharePoint file that
you checked out, you can check it back in so that others can edit it. See "Checking In
SharePoint Files" on page 317.
3. (Option #2) Map/open/edit/synchronize copies of SharePoint files After you connect to a SharePoint server, thus populating the SharePoint Explorer, you can open and edit
any of the files in it. However, keep in mind that when you do this, you are editing the actual
files existing on the SharePoint site. But there is an alternative. You have the option of copying any of the SharePoint files to your Flare project. That way you can edit copies of the files
locally rather than working directly on the actual files located on the server. Following are the
steps for using this method.
a. Copy and map files You can right-click on any files in the SharePoint Explorer and
copy them to your Flare project. When you do this, you can map the copied files in
your project to the source files on the SharePoint server. See "Copying and Mapping
This is a different process than that of importing files, which you can do elsewhere in
Flare. Files that are brought into a project using a traditional import process can be
connected to the source file, but only in one direction (i.e., files can be updated from
the source to the imported file in the project). On the other hand, files that are copied
from the SharePoint Explorer can be connected via mappings to the source files in two
- 311 -
MADCAP FLARE
directions (i.e., files can be updated from the source to the copied file or from the copied file to the source).
b. Manage mappings If you copy SharePoint files, you should create mappings (connections) between the copies of the files that you bring into your project and the source
files on the SharePoint server. You can do this at the point that you copy those files
into your project. You can also manage these mappings whenever necessary through
the Map Files and Folders dialog. This involves the ability to create, change, or remove
mappings. See "Managing Mappings of SharePoint Files" on page 320.
c. Open and edit files You can open a copy of a SharePoint file from the Content
Explorer by simply double-clicking it, just as you would open any other content file in
Flare. If it is a file type not supported in Flare, you will be directed to open the file in
its default application. See "Opening SharePoint Files" on page 314.
d. Synchronize files After you map project files to source files located on a SharePoint
server, you can synchronize them to ensure that each file contains the same content.
This process allows you to import content from SharePoint files, export content from
mapped files in the project to SharePoint, or keep the most recently modified content.
See "Synchronizing SharePoint Files" on page 321.
If you attempt to synchronize files and Flare detects a conflict (i.e., a mapped file has
been modified both locally and in its mapped location), a dialog opens so that you can
take the appropriate action. For more information see the online Help.
Other SharePoint Tasks
Following are some additional tasks related to SharePoint integration that you might perform.
n
Publish output to SharePoint You can select a SharePoint server as a destination type.
This allows you to quickly publish your generated Flare output files to a location on your
SharePoint server. See "Creating Publishing Destinations" on page 480 and "Publishing Output to Destinations" on page 484.
n
Manage templates SharePoint servers are available for browsing when you are working
with templates. For more information see the online Help.
- 312 -
Connecting To A SharePoint Server
From the SharePoint Explorer in Flare, you can connect to a specific SharePoint server. You can then
use that window pane to access the files on that server.
How to connect to a SharePoint Server
n
Select File>SharePoint>SharePoint Explorer.
OR
n
Select View>SharePoint Explorer.
The SharePoint Explorer opens. See SharePoint Explorer.
2. In the local toolbar click
.
The Connect to SharePoint Server dialog opens.
3. Enter the path to the SharePoint server.
4. Click
to validate the server.
5. Click OK.
The SharePoint Explorer is populated with files from the server.
- 313 -
MADCAP FLARE
Opening SharePoint Files
After connecting to a SharePoint server, you can open files to edit them.
One option is that you can open the actual SharePoint files that exist on the server (if you decide,
for example, to use the check-out/check-in features). See "Checking Out SharePoint Files" on page
316 and "Checking In SharePoint Files" on page 317.
Another option is to open copies of those files in your project (if you decide to use file mappings and
synchronization). See "Copying and Mapping SharePoint Files" on page 318 and "Synchronizing
For more information about your options for working with SharePoint, see "SharePoint Integration"
on page 310.
How to open a file existing on the SharePoint server
n
OR
n
2. Locate the file that you want to open. You can use the "multi-view" to do this.
n
Double-click the file.
OR
n
Right-click the file and select Open.
OR
n
Click on the file, and in the local toolbar click
.
If it is a file type not supported in Flare, you will be directed to open the file in its default
application.
- 314 -
How to open a copy of a SharePoint file in your project
2. All copies of SharePoint files that you added to your project will be located somewhere in the
Content folder (in the root itself or under subfolders where you may have placed files when
copying them to Flare). Locate the file that you want to open. You can use the "multi-view" to
do this.
Expands the folders.
n
Double-click the file.
OR
n
Right-click the file and select Open.
OR
n
Click on the file, and in the local toolbar click
.
If it is a file type not supported in Flare, you will be directed to open the file in its default
application.
- 315 -
MADCAP FLARE
Checking Out SharePoint Files
You can check out SharePoint files from the Flare interface. Checking out a file simply means to activate a "flag" on the SharePoint site indicating that you want to access the file and prevent others
from editing it and conflicting with your changes.
How to check out SharePoint files
n
OR
n
2. Locate the file(s) that you want to check out. You can use the "multi-view" to do this.
3. Select the file(s) that you want to check out. If the window pane is split into two halves, you
can select the appropriate folder on the left side and select the files on the right side. You can
hold the SHIFT key to select a range of files, or you can hold the CTRL key to select individual files.
n
Select File>SharePoint>Check Out.
OR
n
Right-click the file(s) and from the context menu select Check Out.
5. In the dialog that opens, click Check Out.
Note: By default there is a check mark next to all files that were selected. If necessary,
you can click any check box to remove the check mark, which means that file will not be
checked out when you are finished.
- 316 -
Checking In SharePoint Files
When you are finished working on a SharePoint file that you checked out, you can check it back in
so that others can edit it.
How to check in SharePoint files
n
OR
n
2. Locate the file(s) that you want to check in. You can use the "multi-view" to do this.
3. Select the file(s) that you want to check in. If the window pane is split into two halves, you
can select the appropriate folder on the left side and select the files on the right side. You can
n
Select File>SharePoint>Check In.
OR
n
Right-click the file(s) and from the context menu select Check In.
5. Click Check In.
Note: By default there is a check mark next to all files that were selected. If necessary,
you can click any check box to remove the check mark, which means that file will not be
checked in when you are finished.
- 317 -
MADCAP FLARE
Copying And Mapping SharePoint Files
After you connect to a SharePoint server, you can copy any of the SharePoint files to your project,
mapping them to the source files at the same time.
This is a different process than that of importing files, which you can do elsewhere in Flare. Files
that are brought into a project using a traditional import process can be connected to the source file,
but only in one direction (i.e., files can be updated from the source to the imported file in the
project). On the other hand, files that are copied from the SharePoint Explorer can be connected via
mappings to the source files in two directions (i.e., files can be updated from the source to the copied file or from the copied file to the source).
How to copy and map SharePoint files
1. Make sure the SharePoint Explorer is open. If it isn't, select View>SharePoint Explorer.
2. Locate the file that you want to add to the project. You can use the "multi-view" to do this.
- 318 -
3. Right-click on the file and from the context menu select Copy to Project.
4. In the dialog that opens, find and select the location in your project that you want to add the
file. Again, you can use the multi-view buttons to navigate to folders in your project.
5. Click OK.
6. In the Copy to Project dialog select Keep file synchronized (create mapping).
7. Click OK. The file is added to the project, as you can see by opening the Content Explorer. If
you selected to map the file, a small orange icon is shown next to it.
- 319 -
MADCAP FLARE
Managing Mappings Of SharePoint Files
If you copy SharePoint files to your project, you can create mappings (connections) between the
copies of those files that you bring into your project and the source files on the SharePoint server.
You can do this at the point that you copy those files into your project (see "Copying and Mapping
SharePoint Files" on page 318). You can also manage these mappings whenever necessary through
the Map Files and Folders dialog. This involves the ability to create, change, or remove mappings.
How to manage mappings of SharePoint files
1. Select Tools>Manage Mappings.
The Map Files and Folders dialog opens.
2. Use the dialog to do any of the following:
Create/change a mapping:
a. If you are creating a new mapping, in the blank row click in the Project Path cell. If
you are changing an existing mapping, in the appropriate populated row click in the
Project Path cell.
b. In that cell click
.
c. In the dialog that opens, find and double-click the copy of the file located in your
project.
d. Click in the External Path cell.
e. In that cell click
.
f. In the dialog that opens, find and double-click the source file located outside of your
project.
Remove a mapping:
a. Click on the icon on the far left side of the row you want to delete. This highlights the
entire row.
b. At the bottom of the dialog click Remove.
3. Click OK.
- 320 -
Synchronizing SharePoint Files
After you map project files to source files located on a SharePoint server, you can synchronize them
to ensure that each file contains the same content. This process allows you to import content from
SharePoint files, export content from mapped files in the project to SharePoint, or keep the most
recently modified content.
How to synchronize SharePoint files
1. Select Tools>Synchronize Mapped Files.
The Synchronize Files dialog opens.
By default only files that are out of sync are listed. However, you can click
files that are already synchronized, and you can click
to refresh the list.
to also show
2. From the drop-down field at the top, select any of the following options:
n
Synchronize Files This imports external source files into the project, overwriting the
copies (if the external files have been modified most recently). And it also exports
copies of files in the project, overwriting external source files (if the copies in the
project have been modified most recently).
n
Import Files For all out- of-sync files, this imports external source files into the
project, overwriting the copies (regardless of which files have been modified most
recently).
n
Export Files For all out-of-sync files, this exports copies of files in the project, overwriting external source files (regardless of which files have been modified most
recently).
3. Make sure there is a check mark next to each pair of files that you want to synchronize and
click Synchronize.
4. In the message that displays, click OK.
Note: In the list of files, you can click
size.
to see more details, such as the modified date and file
- 321 -
MADCAP FLARE
Snippets
Snippets are pre-set chunks of content that you can use in your project over and over. Snippets are
used for longer pieces of content that you can format just as you would any other content in a topic.
In snippets you can also insert tables, pictures, and whatever else can be included in a normal topic.
The major benefit of using snippets is that you only have to create your content once, rather than
having to type the same information in each topic where you want to use it. If you need to modify
the content of a snippet, you only need to change it in one place and the change is made automatically everywhere that the snippet is added.
E X AMPLE
Let 's say y ou are writ ing a manu al abou t d ogs. In one t op ic, y ou hav e creat ed a colorful t able wit h p ict u res t hat list s t he t op fiv e breed s. Let 's say y ou want t o p lace
t hat same t able in sev en ot her t op ics. You hav e a choice. (1) You can re-creat e t hat
t able manu ally in each of t hose t op ics. (2) You can cop y t he first t able and p ast e it
int o t he ot her t op ics. This is a bet t er solu t ion, bu t if y ou need t o make changes t o
t he t able in t he fu t u re, y ou 'll need t o d o so in all eight t op ics. (3) You can creat e a
snip p et from t he t able and insert it int o each of t he ot her t op ics. This is t he best
solut ion becau se, if y ou need t o make changes in t he fu t u re, y ou only need t o d o so
wit hin t he snip p et and t he changes are au t omat ically reflect ed in all eight t op ics.
Snippets are contained in their own files (using an .flsnp file extension). You can therefore share
them with other authors or use them in other projects. If you insert a snippet that is stored outside
of your project, the file is copied to your project. Snippet files are stored in the Content Explorer,
within the Resources\Snippets folder.
- 322 -
Text And Block Snippets
You can create a text snippet or a block snippet. This is determined by the way you insert the snippet. If you insert a snippet on a blank line in a topic, it is inserted as a block snippet and takes up
all of the room so that no other content can be added. If you insert a snippet on a line where other
content exists, it is inserted as a text snippet. Therefore, if you want to insert a snippet on a blank
line and also type other text before or after it, you need to type the text first and then insert the snippet afterwards. Also, if you have a snippet containing multiple paragraphs and insert it within a
line of text, the snippet becomes just one continuous line of text because it is a text snippet.
When you create a text or block snippet, it displays surrounded by brackets (if you have markers
turned on).
Condition Tags And Snippet Conditions
You can apply a condition tag to a snippet so that it is included in some targets but not in other targets. See "Applying Condition Tags to Content" on page 441.
You can also create snippet conditions. Snippet conditions are condition tags that you can apply to
content within snippets. With snippet conditions, you can separate certain snippet content so that
it displays in some topics or master pages but not in others. This allows you to use one snippet for
many purposes, rather than having to create multiple snippets. Whereas regular conditions are
included or excluded at the target level, snippet conditions are included or excluded at the topic or
master page level. For more information see the online Help.
- 323 -
MADCAP FLARE
Snippets And Auto Suggestions
Flare recognizes when you are typing content that matches existing snippets in your project. This
makes it a very fast and convenient way to single-source your content. For more information see the
online Help.
E X AMPLE
Let 's say y ou work on a t eam of 15 writ ers and t here are a series of snip p et s in all of
y our p roject s t hat begin wit h t he same t hree word s—For more informat ion…
Perhap s each p erson knows t o st art t y p ing t hose word s in cert ain p laces. Bu t what
if a snip p et alread y exist s wit h t he fu ll cont ent t hat t he writ er need s? Wit hou t knowing t hat , a p erson might sp end t ime t y p ing all of t he cont ent , and may be ev en
creat e a new snip p et for fu t u re u se. Bu t if Au t o Su ggest ion is enabled , as soon as a
p erson t y p es a cert ain nu mber of charact ers, all mat ching snip p et s are shown in t he
Aut o Suggest ion p op u p . Therefore, t he writ er can qu ickly find and select t he ap p rop riat e snip p et .
- 324 -
Tasks Associated With Snippets
Following are the main tasks involved with using snippets.
n
Create snippets from content If you have already added content in your topic and want
to turn that content into a snippet, you can create a snippet out of that existing content
using the Format menu. See "Creating New Snippets from Existing Content" on the next page.
n
Add snippets You can add a new snippet (without necessarily having any topic open). See
"Adding New Snippets" on page 327.
Note: You can also import an existing snippet from outside your project.
n
Insert snippets After you create or add snippets, you can insert them into any topic in your
project. See "Inserting Snippets" on page 328.
Note: You can also create nested snippets (i.e., a snippet within a snippet). To do this,
simply open a snippet and then insert another snippet into it.
n
Edit snippets You cannot modify the snippet at its location in the topic. When you insert a
snippet into the topic, the content is displayed, but it is held in a separate snippet file. In the
topic the snippet marker is represented by brackets. To modify a snippet you need to open it
from the Content Explorer and make changes to it in the XML Editor. See "Editing Snippets"
on page 330.
- 325 -
MADCAP FLARE
Creating New Snippets From Existing Content
The following steps show you how to create new snippets from existing content.
How to create a new snippet from existing content
1. Open the topic.
2. In the XML Editor highlight the content that you want to turn into a snippet.
3. Select Format>Create Snippet.
4. In the Snippet File field, type a new name for the snippet.
It is recommended that you leave the project folder selection as "Resources/Snippets" (or
select a subfolder that you have created in the Snippets folder). After the snippet is created,
you can see the snippet file in the Content Explorer.
5. If you want the snippet to replace the highlighted text in the topic, make sure that a check
mark is displayed in Replace Source Content with the New Snippet.
6. Click Create. The snippet is added to the Content Explorer and opens in the topic page in
the XML Editor. The snippet is surrounded by brackets (if markers are turned on).
- 326 -
to save your work.
Adding New Snippets
The following steps show you how to add new snippets.
How to add a new snippet
1. Select Project>Add Snippet. The Add New Snippet dialog opens.
n
n
3. You should leave the Folder selection set to "Resources\Snippets" or select a subfolder that
you created within it. After the snippet is created, you can see the snippet file in the Content
Explorer.
4. In the File Name field, type a new name for the snippet.
5. (Optional) Click
. In the Stylesheet field, select a style sheet to associate with the new
snippet. If you do not have a style sheet in your project, this field remains blank.
6. Click Add. The Copy to Project dialog opens. It displays information for the new snippet file
and lets you know that it will be copied to your project.
7. Click OK. The snippet is added to the Content Explorer and opens in its own page in the
XML Editor with some default text for you.
8. Now simply click inside the snippet page in the XML Editor and start typing text (replacing
the default text shown) or adding any other elements (e.g., styles, tables, images, hyperlinks,
multimedia) appropriate for the snippet.
to save your work.
- 327 -
MADCAP FLARE
Inserting Snippets
After you create or add snippets, you can insert them into a content file (e.g., topic, snippet). You
can do this by using the Insert menu or a shortcut button, which lets you search for a snippet, or
you can simply drag an existing snippet from the Content Explorer.
How to insert a snippet using a menu or button option
2. Place your cursor where you want to insert the snippet.
n
In the local toolbar at the top of the XML Editor click
.
OR
n
Select Insert>Snippet.
OR
n
On your keyboard press CTRL+R.
4. In the Insert Snippet Link dialog, select a snippet file to insert. You can either select a snippet
already in the project (from the list) or you can click
to find and select a snippet file outside of the project.
Note: If you want to select a snippet from the list, you can click on the column headings
(File, Path) to sort the list by that category.
Note: If you want to select a snippet that you recently inserted somewhere in your
project, click the down arrow in the field next to
and select the snippet from the list.
Note: If you select a snippet file outside the project, that file is then copied and placed
inside the project. The image file is stored in the Resources\Snippets folder of the Content
Explorer.
- 328 -
5. Click OK. The snippet is inserted and is surrounded by brackets (if markers are turned on).
to save your work.
How to insert a snippet by dragging it from the Content Explorer
2. Open the Resources folder and then the Snippets subfolder, where you have stored the
snippet you want to insert.
3. Drag the snippet from the Content Explorer to the location where you want it in the topic and
drop it.
to save your work.
- 329 -
MADCAP FLARE
Editing Snippets
After you create or add a new snippet to your project, you can insert it into any of your topics. Later,
if you can decide that the snippet needs to be altered, you can do so easily using the steps below.
When you edit a snippet, the changes are automatically reflected in any topics where you have
inserted the snippet previously.
How to edit a snippet
1. Use one of the following methods to open the snippet that you want to modify:
n
Right-click on the snippet in a topic where it is inserted and select Open Link.
OR
n
Locate the snippet in the Resources\Snippets folder in the Content Explorer and double-click it.
2. In the XML Editor make the necessary changes to the snippet, just as you would edit a topic.
- 330 -
to save your work.
Tables
A table in Flare is much like it is in any word processing program, such as Microsoft Word, or in a
printed textbook. A table is a group of intersecting columns and rows that you can add to a topic for
various purposes, such as comparing different elements.
Tasks Associated With Tables
Following are the main tasks for using tables in Flare.
n
Insert tables You can insert a table using the Insert Table dialog. See "Inserting Tables into
Topics" on the next page.
n
Edit tables In addition to simply clicking in cells and typing text, there are several ways
that you can edit tables after inserting them into topics. For more information see the online
Help or the Flare Styles Guide.
n
Create a list of tables You can use the list-of proxy to generate a list of various types of elements (e.g., tables, images) in your output, with links to the corresponding content. For
- 331 -
MADCAP FLARE
Inserting Tables Into Topics
You can create a table using the Insert Table dialog, which lets you specify various properties and
settings for the table while you create it. Another option is to use the Insert Table grid, which lets
you create a simple table by quickly selecting squares displayed from the Insert Table button; this
method is faster but does not let you specify properties and settings for the table at the point of creation.
How to create a table using the Insert Table dialog
2. In the XML Editor place your cursor where you want to add the table.
n
Select Table>Insert>Table.
OR
n
Make sure the Text Format toolbar is open (View>Toolbars>Text Format). Then
click the face (not the down arrow) of the Insert Table button.
The Insert Table dialog opens.
4. Select the General tab and modify the options as necessary.
Table Size:
- 332 -
n
Number of columns Enter the number of columns for the table.
n
Number of rows Enter the number of rows for the table.
n
Number of header rows Enter the number of header rows for the table. A header
row can be used to hold titles for the different columns in the table.
n
Number of footer rows Enter the number of footer rows for the table. A footer row
can be used to hold footnote information about the table.
Table Caption:
n
Text Enter a caption (or title) for the table. This caption can be placed above the table
or below it.
n
Above table Select this option if you want to place the caption above the table.
n
Below table Select this option if you want to place the caption below the table. However, due to an issue with Internet Explorer, this option places the caption above the
table in outputs based on Internet Explorer.
Summary: You can enter a summary for a table. This adds the "summary" attribute to the
<table> tag and is used to help make your output more accessible to individuals with disabilities.
AutoFit Behavior:
n
AutoFit to contents Automatically sets the column widths to the same width as the
table content.
n
AutoFit to window Automatically sets the table width to the same width as the output window.
n
Fixed column width Sets the column widths to the width that you specify. Select
the down arrow next to this field and set the width in the popup.
Align: Aligns the entire table either to the left, right, or center of the topic.
Table Style: You can select to use either a table style sheet or a <table> style from a regular
topic style sheet. Whichever one you choose will control the look of the table that you insert.
When you add a table style sheet to your project, it is stored in the Resources\TableStyles subfolder in the Content Explorer.
- 333 -
MADCAP FLARE
- 334 -
n
Table Style Select this option if you want to use a table style sheet to control the look
of the table. You can then select an existing table style sheet from the drop-down list.
n
If you do not yet have a table style sheet that you want to use, click the face of
this button to open the Select Table Style Template dialog. This lets you create new
table style sheet. If you click the down arrow next to the button, you can select Print
Style. This opens the Select Table Style dialog, which you can use to specify another
table style to be used specifically for printed output. However, it is recommended that
you use a medium instead of the "Print Style" option.
n
Style Class Select this option if you want to use a regular topic style sheet to control
the look of the table. You can then select the main <table> style tag from the dropdown, or you can select any class that you have added under that tag. You can create
classes for the <table> tag in the Stylesheet Editor; those classes will then become available in this drop-down field.
- 335 -
MADCAP FLARE
To add a table style to the Insert Table dialog:
a. In the Insert Table dialog, the face of the Create New Table Style button
the down arrow. The Select Table Style Template dialog opens. , not
b. In the Template Folders area, select a folder.
c. In the Templates area, select one of the templates from the folder. You can see a preview of how the table will look in the Preview area below.
d. (Optional) You can type a new name in the New Style Name field.
e. Click OK. The style is added to the Insert Table dialog.
Text to Table: These options are enabled if you have selected text before opening the dialog
to insert the table. This lets you create the table and quickly place all of the selected text into
table cells.
n
None Select this option if you want to create a table but not include any of the selected
text. In other words, that text is removed and replaced with the new table.
n
Paragraphs Select this option if you have selected multiple paragraphs and want to
convert them into a table. Each paragraph will be placed in a separate table cell.
n
Commas Select this option if you have selected text separated by commas and want
to convert it into a table. Each segment of text between a comma will be placed in a
separate table cell.
n
Other Select this option if you have selected text separated by a specific text string
(e.g., semicolons) and want to convert it into a table. After selecting this option, enter
that text string in the field to the right. Each segment of text between the text string
that you specify will be placed in a separate table cell.
5. Select the Borders tab and modify the options as necessary.
n
Outer Borders Click in any of the individual fields (Left, Right, Top, Bottom) to
specify the settings for the table border. If you click the down arrow to the right of all
the fields, the settings will be applied to all of the border fields. When you click the
down arrow or in one of the individual fields, a small popup displays. Use the lowerleft area of the popup to enter a number for the thickness of the border. Use the lowermiddle area to select a unit of measurement (e.g., point, pixel, centimeter) for the
number you entered. Use the upper-right area to select a color for the border. And use
the lower-right area to select a line type (e.g., solid, double, dashed) for the border.
When you are finished, click OK in the small popup.
n
Cell Border Collapse Select whether you want to collapse the cell borders in the
table. If you collapse the cell borders, the row and cell borders of a table are joined in a
single border. If you do not collapse the cell borders, the row and cell borders of a table
are detached.
n
Cell Border Spacing Use this area to increase or decrease the amount of spacing for
a cell border (in pixels).
6. Click OK. The table is added.
- 336 -
to save your work.
How to create a table using the Insert Table grid
2. In the XML Editor place your cursor where you want to add the table.
3. Make sure the Text Format toolbar is open (View>Toolbars>Text Format).
4. Click the down arrow (not the face) of the Insert Table button.
A drop-down gird with a series of horizontal and vertical squares is displayed.
5. Hover over the grid. When you do this, the squares change color to indicate how many rows
and columns will be included in the table. As soon as you click, the new table is inserted.
The table initially looks very plain because it has no properties or style sheet associated with
it. Therefore, you will likely want to open the Table Properties dialog at some point to specify
settings and/or apply a table style sheet to it.
to save your work.
- 337 -
MADCAP FLARE
Tables Of Contents
You can create a TOC by adding books and items with links (to topics, external files, other Help systems, movies, etc.) in a structure that you think would be useful for the individual. End users then
browse through a TOC to find information.
In many cases, Flare provides you with an initial TOC , which you further "build" (or create) using
the TOC Editor. You can use this TOC as your primary, or "master," TOC . At some point, you may
decide to add another TOC to the project . The extra TOCs that you add can then be linked to the
master TOC (see the online Help for more information about linking and merging TOCs).
For print-based output (Adobe PDF, XHTML, Microsoft XPS, Microsoft Word, Adobe FrameMaker),
you need to use the TOC Editor to create a TOC just as you would create one for online output (DotNet Help, HTML Help, WebHelp, WebHelp Plus, WebHelp AIR, WebHelp Mobile). However, there is
a fundamental difference. Performing this task for online output creates an actual TOC in the output, which people use to navigate from topic to topic. This is not the case for print-based output.
Performing this task for print-based output lets you indicate which topics will be included in the output and in what order. In that sense, this TOC functions more as an outline for print-based output.
Therefore, for print-based output, you can think of it as an "outline TOC." If you want to include a
generated TOC in print-based output, you need to use a TOC proxy in a topic instead.
Steps For Using Tables Of Contents
Following are the tasks necessary for including a TOC in your project.
1. Add/open TOC If you do not want to use the initial TOC often provided by Flare, you can
add one. And you can open an existing TOC from the Project Organizer whenever you need to
work on it. See "Adding a Table of Contents" on page 340 and "Opening a Table of Contents"
on page 341.
2. Create TOC You can create a TOC manually or automatically, adding books and links to topics or other files. See "Creating a Table of Contents" on page 342. For information about autogenerating a TOC, see the online Help.
3. Edit TOC entries After you create a table of contents, you can edit the individual entries in
many ways. This includes linking entries to other files, setting titles automatically, and applying condition tags. See "Editing TOC Entries" on page 343.
4. Enable TOC After creating the TOC, you need to enable the TOC in the skin you want to use
for the target (for online output). See "Enabling Tables of Contents in Skins" on page 345.
5. Associate skin with target Now that the TOC is enabled in the skin, you need to associate
that skin with the target you are building (for online output). See "Associating Skins with Targets" on page 412.
6. (Optional) Associate master TOC with a project or target In most situations, you
will have one TOC that you use for a particular output (target). In that case, you simply associate the appropriate TOC with the target. If you have multiple TOCs that you want to
include in the same project or output target, the TOC that you associate with the project or
target serves as the "master" TOC. In your master TOC, you have the option of creating links
- 338 -
to the other TOC that you want to include in the output. If you do not select a TOC, Flare
will use the first one in the project (if there is more than one). If you have specified a master
TOC at the project level and another at a target level, the TOC at the target will take precedence. See "Associating a Master Table of Contents with a Project" on page 345 and "Associating a Master Table of Contents with a Target" on page 345.
Additional Steps For Print-based Output
For print-based output, the following additional steps may necessary when working with an "outline
TOC."
1. Include print topics in "outline TOC" You need to make sure that all of the topics to be
included in your printed output (those that are ONLY for printed output, as well as those
that are for printed AND online output) are added to an "outline TOC." For more information
see the online Help or the Flare Printed Output Guide.
2. (Optional) Specify chapter breaks with TOC If you are creating print-based output
with page layouts, you may want to complete this task. After you create a page layout and
configure its frames and settings as necessary, you need to associate the page layout with the
appropriate content. In most cases, you will probably want to associate different page layouts
with various entries in your "outline TOC" (so that different page layouts can be used for different parts or "chapters" in a manual)—see Specifying Chapter Breaks and Page Layouts.
Otherwise, you would associate a single "master" page layout with an entire target or project;
in that case, the same page layout will be applied to all topics in that target or project. Whenever you associate a page layout with a TOC entry, you must first create a chapter break in
order to do so. For more information see the online Help or the Flare Printed Output Guide.
3. (Optional) Specify section breaks with TOC If you are creating Word or FrameMaker
output with master pages (or if you want to use "section" auto-numbers), you may want to
complete this task. After you create a master page for print output and configure it as necessary, you need to associate the master page with the appropriate content. In many cases,
you will probably want to associate multiple master pages with various entries in your outline
TOC (so that different master pages can be used for different parts or "chapters" in a manual).
Otherwise, you would associate a single master page with an entire target; in that case, the
same page layout will be applied to all topics in that target. Whenever you associate a master
page with a TOC entry, you must first create a section break in order to do so. For more information see the online Help or the Flare Printed Output Guide.
- 339 -
MADCAP FLARE
Adding A Table Of Contents
In many cases, Flare provides you with an initial TOC , which you further "build" (or create) using
the TOC Editor. You can use this TOC , but you may decide to add more TOCs to the project so
that you can have different TOCs for different outputs. The steps below show you how to add a new
TOC.
How to add a table of contents
1. Select Project>Add Table of Contents. The Add TOC dialog opens.
n
n
3. In the File Name field, type a new name for the TOC.
4. Click Add.
5. Click OK.
The TOC is added to the TOCs folder in the Project Organizer. The TOC Editor opens to the
right, with the page for the new TOC shown and some initial TOC books and entries added
for you.
- 340 -
Opening A Table Of Contents
You can quickly open a TOC anytime you need to work on it.
How to open the master TOC
n
In the Project toolbar, click
View>Toolbars>Project.)
. (If you do not see the Project toolbar, select
OR
n
Press CTRL+F8 on your keyboard.
How to open a specific TOC
2. Double-click the TOCs folder. The TOC(s) in your project are displayed.
3. Double-click the TOC that you want to open. The TOC opens in the TOC Editor to the right.
- 341 -
MADCAP FLARE
Creating A Table Of Contents
The following steps show you how to manually create a TOC by adding books and links to topics,
movies, external files, other TOCs, browse sequences, or other Help systems in any kind of structure
you want. You will quickly find that creating a TOC is quite an easy process.
How to create a table of contents
1. Open your TOC. The easiest way to do this is to click the Open Master TOC button in the
Project toolbar. To open this toolbar, select View>Toolbars>Project.
If you need to add a new TOC file, you can select Project>Add Table of Contents and
complete the options in the dialog. After they are added, TOC files are stored in the TOCs
folder in the Project Organizer. When creating a new project, Flare provides you with an initial TOC; therefore, you may not need to add one.
3. (Optional) If you want to select and add multiple topics to the TOC at the same time (as
opposed to one topic at a time), complete these steps:
a. In the local toolbar of the Content Explorer, click the Show Files button
.
b. On the right half of the Content Explorer, find and select the folder and topic files that
you want to include in the TOC. You can hold the SHIFT key to select a range of files,
or you can hold the CTRL key to select individual files.
Note: Make sure you do not select the "Resources" folder in the Content Explorer,
which holds your ancillary content files (e.g., images, style sheets). If you do, that
folder and its contents will also be included in the TOC.
4. Drag topic files (and folders, if applicable) from the Content Explorer to the TOC Editor.
Note: For print-based output, make sure to also include any topics that you created with
TOC, index, or glossary proxies in order to produce those types of generated content in
the output.
Also, you can use the buttons in the TOC Editor local toolbar to add elements (e.g., books,
topic pages) to the TOC and to determine how they behave (e.g., link them to topics, external
files, other TOCs). For details see the online Help.
- 342 -
to save your work.
Editing TOC Entries
After you create a table of contents, you can edit the individual entries in the following ways.
n
Auto-generate In many cases, Flare provides you with an initial TOC , which you further
"build" (or create) using the TOC Editor. You can easily create a TOC manually, adding
books, as well as links to files, in any kind of structure you want. Another option is to autogenerate a TOC. For more information see the online Help.
Note: This feature is for online output types only (DotNet Help, HTML Help, WebHelp,
WebHelp Plus, WebHelp AIR, WebHelp Mobile). It is not intended for print-based outputs (Adobe PDF, XHTML, Microsoft XPS, Microsoft Word, Adobe FrameMaker).
n
Auto-merge You can determine where other Flare project outputs are merged relative to
your "master" project's TOC if you are generating WebHelp Plus output and you are publishing the files to a Web server running Microsoft IIS. For more information see the online
Help.
n
Auto-numbers - flow You can specify the flow for auto-numbers if the output is to be split
into multiple sections or chapters. For more information see the online Help.
n
Browser frame You can specify the kind of browser frame that a linked file should open
when a user clicks the TOC entry in the output. For more information see the online Help.
n
Chapters - breaks You can specify that the TOC entry should result in a new chapter when
building print-based output. For more information see the online Help.
n
Condition tags You can associate condition tags with a particular TOC entry so that it
appears in some outputs but not in other outputs. See "Applying Condition Tags to Content"
on page 441.
n
Icon for HTML Help You can select an icon to use for a particular TOC entry in HTML
Help output. For more information see the online Help.
n
Label You can change the label text for a TOC entry. For more information see the online
Help.
n
Link to browse sequence You can link a TOC entry to a browse sequence. For more information see the online Help.
n
Link to CHM file You can link a TOC entry to an HTML Help (CHM) file that you have
already brought into your project (perhaps via the external resources feature), or you can
select a CHM file located elsewhere, in which case a copy of it is added to your project.. That
CHM file will then be merged with the current project when you build the output. For more
n
Link to external Help system You can link a TOC entry to the output file from another
Help project. This option is useful if you are sharing a Help system with another author and
need to retrieve it from a remote location. You can select Flare output files (e.g., DotNet Help
and WebHelp). That output file will then become linked to the TOC entry and merged with
the current project when you build the output. For more information see the online Help.
n
Link to Flare project and target You can link a TOC entry to a target in a Flare project.
(Make sure you select a target of the same output type as the current project.) That project
- 343 -
MADCAP FLARE
and target will then become linked to the TOC entry and merged with the current project
when you build the output. For more information see the online Help.
n
Link to Mimic movie You can link a TOC entry to a MadCap Mimic movie or project. For
n
Link to TOC You can link a TOC entry to another TOC. For more information see the online
Help.
n
Link to topic If you drag topics from the Content Explorer to the TOC Editor, the entry that
is created is automatically linked to that topic. If you want to change the link, or if you have
created an entry that is not yet linked to a topic, you can easily do so manually. For more
n
Mark as new You can specify whether a TOC entry should be displayed as "new" in the
output. For more information see the online Help.
n
Page layouts You can specify a particular page layout that should be used in the output,
starting at the point of the selected entry. In order to specify a page layout, you must also
create a chapter break. For more information see the online Help.
n
Page numbers You can specify how page numbering should work in the output, if you have
inserted page numbers into the page layout or master page. This includes the ability to specify the starting number, whether the numbers should continue from the previous pages, and
the kind of format to use (e.g., decimal, Roman, alpha). For more information see the online
Help.
n
Sections - breaks You can specify that the TOC entry should result in a new section when
building print-based output (and specify master pages). For more information see the online
Help.
n
Skin You can add skins to your project to help create a look and feel for online output that
you generate. After you create a TOC , you can associate a TOC entry with a particular skin.
See "Skins" on page 405.
n
Style class For certain elements of the online output window (e.g., navigation pane, TOC or
Mobile skins
to make changes for WebHelp Mobile output. If you are generating one of
the WebHelp output types, you can use the TocEntry style in the Styles tab of the Skin Editor
to change the look of individual entries in your TOC. You can also select the TocEntry style in
the Skin Editor and use the Add Class button in its local toolbar to create classes of that
style. If you do that, you can select a particular class for a TOC entry so that you can give it
the look you want. For more information see the online Help.
n
Title You can automatically set the name of the TOC entry as the title for the topic in the output. This overrides the title that you may have provided for the topic in the Properties dialog
for that topic. For more information see the online Help.
- 344 -
Enabling Tables Of Contents In Skins
After you create a TOC manually or automatically, you need to enable TOCs in the skin that you
intend to use for your target.
How to enable a TOC in a skin
1. Open the skin from the Project Organizer.
For more information see "Skins" on page 405.
2. On the General tab, click the TOC check box so that it contains a check mark.
to save your work.
Associating A Master Table Of Contents With A Project
The following steps show you how to associate a master TOC with a project.
How to associate a master TOC with a project
1. Select Project>Project Properties. The Project Properties dialog opens.
2. Select the Defaults tab.
3. Click in the Master TOC field, and from the drop-down, select the TOC.
4. Click OK.
5. Press CTRL+SHIFT+S or click
to save your work.
Associating A Master Table Of Contents With A Target
The following steps show you how to associate a master TOC with a target.
How to associate a master TOC with a target
2. On the General tab in the Target Editor, click the drop-down arrow in the Master TOC
field, and select the TOC that you want to associate with the target.
to save your work.
- 345 -
MADCAP FLARE
Text Boxes
You can insert a box into a topic and add content to it. The text box is separate from the regular text
in the topic and can be positioned in a variety of places on a page (e.g., aligned left on the page, outside frame, center of column). You might add a text box, for example, to create an example or case
study that runs alongside the main text in a topic, in order to enhance the reader's understanding of
the main text. See "Inserting Text Boxes" on page 348 and "Object Positioning" on page 400.
E X AMPLE
Let 's say y ou want t o ad d a case st u d y t hat is p osit ioned next t o t he main bod y t ext
on a p age. Therefore, y ou insert a t ext box wit h a bord er and u niqu e background
color t o make it st and ou t . You p osit ion t he t ext box t o t he left of t he bod y frame on
a p age. That way , it is clear t o t he read er t hat t he case st u d y is int end ed t o p rov id e
ad d it ional informat ion p ert aining t o t he bod y t ext on t hat p age.
When you insert a text box, you can make selections to affect the look of the box (e.g., border background, size). In addition, text boxes are based on <div> style tags that you can select when inserting them. Therefore, you can always change the settings on a <div> tag to automatically modify the
look of all text boxes using that same <div> tag. For more information about using styles, including
steps, see the online Help or the Flare Styles Guide. For basic information about styles in this manual, see "Styles and Style Sheets" on page 362.
- 346 -
Note: Text boxes are not supported in Microsoft Word output.
- 347 -
MADCAP FLARE
Inserting Text Boxes
You can insert a text box into a topic. This box can hold text outside the normal flow of topic content.
How to insert a text box
2. Place your cursor in the topic where you want to insert the text box.
If your cursor is on the same line as a paragraph, the text box will be placed after that paragraph.
If you want the text box to be placed outside of a page frame, simply choose the location nearest to that location. You can adjust the exact positioning later.
3. Select Insert>Text Box. The Insert Text Box dialog opens.
4. Select the Text Box tab.
5. Select one of the <div> tags to use for the text box. You can use the parent <div> tag, or you
can select a class if you have created one for it previously in your style sheet. The <div> tag is
just one way to change the look of the text box.
6. In the Size section, enter a height and width for the text box. Enter a number and a unit of
measurement.
The next several steps let you adjust the look of this specific text box. However, if you want
all of your text boxes to share some of the same features, you can instead provide the following settings on the <div> tag instead. For more information see the online Help or the
Flare Styles Guide.
7. In the Position section, you can select a Float and a Clear setting.
Float Use this field to specify where to place the text box on the page.
- 348 -
n
None Does not place the text box in a specific location.
n
Left Positions the text box on the left side of the page frame, allowing you to type text
to the right of the text box.
n
Right Positions the text box on the right side of the page frame, allowing you to type
text to the left of the text box.
n
Center of Column Positions the text box in the center of the column on the page.
n
Outside Left Margin Positions the text box beyond the left margin of the topic text.
n
Outside Right Margin Positions the text box beyond the right margin of the topic
text.
n
Outside Frame Positions the text box outside of the page frame.
n
Outside Frame, Top Align Positions the text box outside of the page frame, as well
as aligning it with the top of the frame.
n
Left of Frame Positions the text box to the left of the page frame.
n
Right of Frame Positions the text box to the right of the page frame.
n
Center of Frame Positions the text box both vertically and horizontally in the
middle of the page frame.
Note: Some of these options may not be available until after you initially insert a text
box. To view and use all options, you can right-click in the text box after it is inserted and
select Text Box to edit the properties.
Clear Use this field to position a text box so that it is "clear" of an adjacent text box. For
example, let's say you have already inserted a text box and applied the float left property to
it. If you then insert another text box immediately after the first text box, you want to make
sure that the second text box doesn't rest next to the first text box. Instead, you want the second text box to be placed completely below the first text box. Therefore, you can apply a clear
property to the second text box.
n
None Does not apply the clear property to the text box.
n
Left Side The text box will be placed below the bottom outer edge of a previous text
box that is floating left.
n
Right Side The text box will be placed below the bottom outer edge of a previous text
box that is floating right.
n
Both Sides The text box will be placed below the a previous text box, whether it is
floating left or right.
8. Select the Borders tab.
9. You can use the Borders section to create a border around the text box.
f. Click OK.
- 349 -
MADCAP FLARE
10. Set the options in the Padding section. Click in any of the individual fields (Left, Right,
Top, Bottom ) to specify the settings for the padding. This adds extra space between a text
box's border and the text within it. In the left side of the field, enter a number for the amount
of padding. In the right side of the field, select a unit of measurement (e.g., point, pixel, centimeter) for the number you entered.
If you click the down arrow to the right of all the fields, the settings will be applied to all of
the padding fields. When you click that down arrow, a small popup displays.
11. Use the Background tab to specify the settings that you want for the background.
n
dialog.
a. Next to the Image field, click the Browse button. The Insert Picture dialog opens.
b. Select an image file to insert. You can do this in one of the following ways:
n
Select an image already in the project by finding and selecting it in the built-in
tree.
OR
n
Click
to find and select an image file outside of the project.
Note: If you want to select an image file that you recently inserted somewhere in
your project, click the down arrow in the field next to the Browse button and select
the file from the list.
c. Click OK.
d. If you want the background image to repeat, select one of the options from the Repeat
and Y fields.
12. In the Insert Text Box dialog, click OK.
- 350 -
to save your work.
Note: After inserting a text box, you can make further modifications to change the way that it
looks. For more information see the online Help or the Flare Styles Guide.
- 351 -
MADCAP FLARE
Variables
Variables are pre-set terms that you can use in your project over and over. They are stored in "variable sets," which can hold multiple variables. Flare provides you with an initial variable set, but
you can add as many additional variable sets as you like.
Variables are used for brief, non-formatted pieces of content (such as the name of your company's
product or your company's phone number). There are different kinds of variables: (1) those you
create, (2) system variables (e.g., date and time; Chapter, Section, and Volume numbers), (3) Heading variables, and (4) Running Head variables. Some of these are especially useful for page headers
and footers in print-based output.
Variable Components
A variable has two main components—the variable name and the variable definition.
E X AMPLE
An examp le of a v ariable name is "C omp any Name. " The d efinit ion for t hat v ariable
name might be "AC ME Incorp orat ed . " Using t hat examp le, if y ou were t o insert t he
C omp any Name v ariable int o a p aragrap h of a t op ic, t he p hrase "AC ME Incorp orat ed " wou ld be ad d ed at t hat sp ot and shown in t he ou t p u t .
Types Of Variables
Following are the main categories of variables that you can use.
n
Custom variables These are variables that you can create in variable sets. They can be used
for virtually any purpose (product names, company information, terms that are used
frequently). See "Creating New Variables" on page 357.
n
System variables Flare lets you insert the system date and time as variables. The global format in windows controls the format dates and times in variables. To insert a system variable,
you simply select Insert>Variable. Then select System and choose the specific variable.
In addition, for Adobe PDF, Microsoft XPS, and XHTML output, you can insert system variables in page layout frames that display your chapter, section, or volume numbers (if you are
using auto-numbers to identify the various parts of a manual). For more information see the
online Help or the Flare Printed Output Guide.
n
Heading variables You can insert Heading variables into page layouts or master pages in
order to automatically display text based on the <h1> through <h6> heading styles that you
use in your project. Like Running Head variables, they are useful when creating print-based
output. It's an easy way, for example, to automatically display a chapter title in the header
of a chapter. For Adobe PDF, Microsoft XPS, and XHTML output, you can also use Heading
variables to automatically display glossary headings/terms and index headings/terms in a
page layout frame. For more information see the online Help or the Flare Printed Output
Guide.
n
Running Head variables In addition to system variables and those you can create (from
- 352 -
the "MyVariables" template), you can also add Running Head variables (using the "Running
HF" template). A Running Head (or Running HF) variable is a special variable that you can
insert into a header or footer in a page layout or a print master page. It lets you display certain text in the header or footer automatically, based on the style associated with the variable.
For example, Running Head variables are useful if you want to include the title of each chapter in a document in a header or footer without having to type them into multiple pages.For
Note: Running Head variables are supported only in Adobe FrameMaker and Microsoft
Word output.
Visual Cues For Variables
When you insert variables into content, there are a few ways to discern that certain content is actually a variable, as opposed to regular text.
Markers
First, markers can be turned on or off, providing a visual cue about the content in the form of brackets. When you insert a variable into a topic with markers turned on, the variable definition is displayed in a marker represented by brackets on either side of the definition. If you cannot see all of
the information in a marker, you can adjust the marker width (at the bottom of the View>Show
menu).
Here is an example of a variable with markers turned on (View>Show>Show Markers):
- 353 -
MADCAP FLARE
Variable N ames
In addition to markers, you can select an option to show variable names. Here is an example of a
variable with variable names turned on (View>Show>Show Variable Names):
H ighlighted Variables
You can also select an option to display variables with a highlighted background (select
View>Show>Highlight Variables). Here is an example:
- 354 -
Tasks Associated With Variables
Following are the main tasks involved with using variables.
n
Add set You can use the initial variable set provided by Flare, and you can add more variable sets if necessary. Each variable set can hold multiple variables. See "Adding Variable
Sets to Projects" on the next page.
n
Create You can create custom variables within a variable set. See "Creating New Variables"
on page 357.
n
Insert You can insert variables into topics (as well as other elements, such as snippets or
page layout frames). See "Inserting Variables" on page 359.
n
Edit After you create a variable, you can easily edit it in the Variable Set Editor. If you
change the definition for a variable that has been inserted into topics, the changes will automatically be reflected in all those topics. See "Editing Variables" on page 360.
- 355 -
MADCAP FLARE
Adding Variable Sets To Projects
The following steps show you how to add a new variable set to your project. You can then open the
variable set and create new variables.
How to add a variable set to a project
1. Select Project>Add Variable Set. The Add Variable Set dialog opens.
n
n
3. In the File Name field, type a new name for the variable set.
4. Click Add.
5. Click OK.
The variable set is added to the Variables folder in the Project Organizer. The Variable Set
Editor opens to the right, with the variable entries shown.
- 356 -
Creating New Variables
The following steps show you how to create a new variable within a variable set.
How to create a new variable
2. Double-click the Variables folder.
3. Double-click a variable set, such as the initial one provided by Flare. If you do not have any
variable sets in the folder, you can easily add one using the Project menu. The Variable Set
Editor opens to the right, with the variables page shown. If you use the "MyVariables" template, Flare provides you with two variables (CompanyName and PhoneNumber) to get you
started. You can delete these variables or modify them to suit your needs.
- 357 -
MADCAP FLARE
4. To create an additional variable, click
with a temporary name for the variable.
in the local toolbar. A new variable row is added,
5. To enter a new name, definition, or comment for a new variable (or for the variables already
provided by Flare), do one of the following:
n
Double-click in a field and type the name, definition, or comment.
OR
n
Click once in a field and press F2 on your keyboard. Then type the name, definition, or
comment.
- 358 -
to save your work.
Inserting Variables
After you create or modify variables, you can insert them into any content file (e.g., topic, snippet)
in your project.
How to insert a variable
2. Place your cursor where you want to add a variable.
n
In the local toolbar at the top of the XML Editor click
.
OR
n
Select Insert>Variable.
OR
n
On your keyboard press CTRL+SHIFT+V.
The Variables dialog opens, with the variable set(s) on the left and the variables associated
with the selected set on the right.
4. On the left, select the appropriate variable set.
5. On the right, select the variable you want to insert.
6. Click OK.
The variable is added, with brackets surrounding it. The bracket shows the variable name and
the variable definition (as long as markers are turned on and the set marker width allows it).
You can adjust the marker width from the Show tags button
to see more or less of the
variable information, and you can also tell Flare to turn off the variable names so that you
only see the variable definition. For more details about markers see the online Help.
to save your work.
- 359 -
MADCAP FLARE
Editing Variables
After you create a variable, you can easily edit it in the Variable Set Editor. If you change the definition for a variable that has been inserted into topics, the changes will automatically be reflected in
all those topics.
How to edit a variable
2. Double-click the Variables folder.
Your variable sets are displayed.
3. Double-click the custom variable set (such as MyVariables) that contains the variable you
want to modify.
The Variable Set Editor opens to the right, with the variables page shown.
4. Double-click in a field and type the name, definition, or comment. (You can also click once in
a field, press F2 on your keyboard. Then type the name, definition, or comment.)
Note: You cannot change system or Heading variables. If you are working with Running
Head variables, you should not change the first part of the definition, but you can change
the style within the definition. For more information see the online Help.
- 360 -
to save your work.
There are numerous features for "dressing up" your output.
Styles and Style Sheets
362
Local Formatting
363
Auto-Numbers
364
Fonts
381
Headings
382
Lists
383
Object Positioning
400
403
Skins
405
- 361 -
MADCAP FLARE
Styles And Style Sheets
One of the most important aspects of Flare is the use of styles and style sheets. Quite simply, styles
are the best, most efficient way to affect the look of your output.
For more details about using styles see the online Help or the Flare Styles Guide, which you can
download from here:
http://www.madcapsoftware.com/documentation/FlareV7/FlareStylesGuide.pdf
Styles are elements that contain formatting settings. You can apply styles to your content to change
the way it looks. Flare works with cascading style sheet (CSS) rules that are specified by the World
Wide Web Consortium, or W3C (http://www.w3.org).
E X AMPLE
The head ing abov e is u sing t he < h2 > st y le t ag (which is short for a " second - lev el
head ing"). Prop ert ies hav e been assigned t o t his st y le t o affect it s look (su ch as
Arial, 12 p t , bold ). We can ap p ly t his st y le t o any block t y p e of cont ent (e. g. , head ings or p aragrap hs). If we were t o change t he color t o green in t he st y le, ev ery head ing or p aragrap h in t he p roject t hat u ses t hat st y le wou ld change t o green
immed iat ely .
An important aspect of CSS is that it is based on community-wide standards set by the W3C. This
means that CSS can be used for any XML-based tool, not just Flare. Tools such as Microsoft Word
and Adobe FrameMaker also use styles, but they are proprietary, which means they can be used only
within that application.
- 362 -
Local Formatting
When you edit the content of a topic, you are working in the XML Editor. Local formatting is a way
to change the look and feel of content directly so that the changes are applied only to that specific
content (as opposed to applying the changes throughout your project via the use of styles). Many
easy-to-use tools are provided for editing and formatting topics locally in the XML Editor to give
them the look and feel you want, without having to know XML at all. Simply open the topic that
you want to format, and use the tool that suits your needs best.
Local formatting (sometimes called "inline" formatting) can be very attractive because it is quick and
easy. However, it is recommended that you use styles instead of local formatting whenever possible.
Although local formatting is very convenient in the short-term, using styles is much more efficient
and can save you a great deal of time in the long-term.
Local formatting tools are available in the following areas.
n
Local toolbar of XML Editor
n
Text Format toolbar (View>Toolbars>Text Format)
n
Local Formatting window pane (View>Local Formatting Window)
n
Font Properties dialog (Format>Font)
n
Paragraph Properties dialog (Format>Paragraph)
For descriptions of the tools in each of these, refer to the online Help.
- 363 -
MADCAP FLARE
Auto-Numbers
Auto-numbering is just what it sounds like—a feature where content is numbered automatically. Of
course, if you want to create simple numbered lists in topics, you can always use Flare's quick list
drop-down options. But if you want an alternative that is more advanced and powerful, you can use
auto-numbering.
Why Use Auto-Numbers?
Auto-numbering can be used for both online and print-based output, but it is especially useful in
print-based output.
Following are just a few reasons for using auto-numbering. For samples of formats that you might
use for these purposes, see "Auto-Number Format Examples" on page 367.
n
Chapter, section, and volume numbers If you are producing output that is organized
into multiple chapters, sections, and/or volumes, you can apply auto-numbers to those different elements. Not only does this let you produce numbers automatically for chapter, section, and volume headings, but you can also incorporate this numbering into other content
(e.g., page numbers, figure captions, table headings).
Note: To generate chapter numbers, you need to create an auto-number format that
includes the {chapnum} command. Then specify chapter breaks in the outline TOC. For
Note: To generate section numbers, you need to create an auto-number format that
includes the {secnum} command. Then specify section breaks in the outline TOC. For
Note: To generate volume numbers, you need to create an auto-number format that
includes the {volnum} command. Second, you need to specify chapter breaks in the outline TOC. Third, you need to specify the auto-number flow for each volume, resetting the
volume number to a specific number. For more information see the online Help or the
Flare Printed Output Guide.
Note: You can also insert Chapter, Section, or Volume Number variables into page layout
headers. By doing this, you can automatically display the correct chapter, section, or volume number at the top or bottom of pages in the output. For more information see the
online Help or the Flare Printed Output Guide.
Note: If you are using chapter or volume auto-numbers and you want these numbers to
be reflected in a print index, you can do so by specifying the auto-numbers at the appropriate locations in your outline TOC (instead of inserting Chapter or Volume Number
- 364 -
variables in a page layout). For more information see the online Help or the Flare Printed
Output Guide.
Note: In order to create chapter and volume auto-numbers in FrameMaker output, you
must split the output into multiple FrameMaker documents. If you are creating one of the
other print-based outputs (PDF, XPS, XHTML, Word), you do not necessarily need to
create multiple documents, but you do need to create chapter breaks for the output. For
n
Paragraphs You can apply auto-numbering to different levels of paragraphs in your project.
E X AMPLE
You might sp ecify t hat t he first - lev el p aragrap hs cont ain nu mber format s such
as 1. 0, 2. 0, 3. 0, and so on. May be y ou r second lev el p aragrap hs wou ld be format t ed as 1. 1, 1. 2, 1. 3, 2. 1, 2. 2, and so on. And finally , t he t hird lev el p aragrap hs might be format t ed as 1. 1. 1, 1. 1. 2, 1. 2. 1, 1. 2. 2, 1. 2. 3, and so on.
n
Figure captions Perhaps you have inserted multiple pictures into your project , with a caption under each image. If you want the captions for each chapter to be numbered (e.g., "Figure 1-1," "Figure 1-2," "Figure 1-3," "Figure 2-1," "Figure 2-2"), you can apply auto-number
formats to that content. If you insert a new figure caption with that format between existing
captions, Flare will renumber them automatically.
n
Table headings Another way to make use of auto-numbering is to apply them to headings
for tables in your project (e.g., Table 1, Table 2, Table 3).
n
Page numbering You can easily include page numbers in content for print-based output
without creating auto-number formats. However, if you want to incorporate volume, chapter,
or section numbers into your pages numbers, you can so by using auto-number formats.
n
Lists As an alternative to using Flare's quick list drop-down options, you can use auto-numbering to create numbered lists for purposes such as step-by-step procedures or outlines.
n
And more… If you can apply a paragraph style to it, you can include auto-numbering in it.
- 365 -
MADCAP FLARE
Steps For Using Auto-Numbers
Whatever you are trying to accomplish when it comes to auto-numbers, there are three basic tasks
that you may complete.
1. Create auto-number formats First, you need to specify what a particular auto-number
will include and what it will look like.
E X AMPLE
If y ou are creat ing a format t o u se wit h figu re cap t ions, y ou might sp ecify t he
format t o d isp lay t he word "Figu re" followed by t he chap t er nu mber, a d ash,
and an increment ed nu mber. You also might want t his format t o ap p ear in
bold font . Finally , y ou might u se a float op t ion so t hat t he au t o- nu mber is
p osit ioned t o t he left of t he p age lay ou t frame where t he relev ant p aragrap h
occu rs.
You can create auto-number formats for styles (which you can easily reuse) or directly for a
specific paragraph. For more information about creating these formats for styles, see "Creating
Auto-Number Formats for Styles" on page 373. For more information about creating these formats for paragraphs, see the online Help.
2. Apply styles with auto-number formats to content After the auto-number format is
created using the style method, you need to indicate where it should be displayed in your content.
E X AMPLE
If y ou p lan t o u se an au t o- nu mber format for figu re cap t ions, y ou ap p ly t he
st y le u sing t hat p art icu lar format t o t he ap p rop riat e locat ions in y ou r t op ics.
For more information about using styles, including steps, see the online Help or the Flare
Styles Guide. For basic information about styles in this manual, see "Styles and Style Sheets"
on page 362.
3. Specify auto-numbering flow for output If you are including volume, chapter, and/or
section auto-numbers in print-based output, you need to indicate where each volume, chapter, or section should begin and end. You also need to provide other specifications, such as
whether the numbering should restart at a specific number, whether it should continue from
the previous list, and the type of numbering format (e.g., Roman, alpha) to be used.
This procedure is especially useful if you have created chapter auto- numbers and need to
ensure that they begin with the correct number at the correct location, after any front matter
(e.g., title page, copyright page, generated table of contents).
For more information see the online Help or the Flare Printed Output Guide.
- 366 -
Auto-Number Format Examples
Following are examples of some common uses of auto-numbering and how you might create autonumber formats for them.
Auto-number format*
GH:VOLUME {volnum}:
How it will look in output**
VOLUME 1: [Add Heading
Title Here]
Where you might use it
A heading to display the volume
number and title.
Note: To generate volume
numbers, you need to create an
auto-number format that includes
the {volnum} command. Second,
you need to specify chapter breaks
in the outline TOC. Third, you
need to specify the auto-number
flow for each volume, resetting
the volume number to a specific
number.For more information see
the online Help or the Flare
Printed Output Guide.
Note: You can also insert Volume
Number variables into page layout headers. By doing this, you
can automatically display the correct volume number at the top or
bottom of pages in the output.
For more information see the
online Help or the Flare Printed
Output Guide.
- 367 -
MADCAP FLARE
Auto-number format*
CH:Chapter {chapnum} -
Chapter 1 - [Add Heading
Title Here]
A heading to display the chapter
number and title.
Note: To generate chapter
numbers, you need to create an
auto-number format that includes
the {chapnum} command. Then
you need to specify chapter breaks
in the outline TOC. For more information see the online Help or the
Note: You can also insert Chapter Number variables into page
layout headers. By doing this,
you can automatically display the
correct chapter number at the top
or bottom of pages in the output.
For more information see the
online Help or the Flare Printed
Output Guide.
A:{n+}.{ =0}
- 368 -
1.0 [Add Paragraph Text
Here]
A paragraph at the first level of your
content. Additional paragraphs using
this same format would be numbered
like this:
2.0
3.0
4.0
Auto-number format*
A:{n}.{n+}
1.1 [Add Paragraph Text
Here]
A paragraph at the second level of
your content. You might indent paragraphs (or styles) using this format.
If so, paragraphs using this same format would be seen as "children" of
first-level paragraphs and numbered
like this:
1.0
1.1
1.2
2.0
2.1
2.2
2.3
A:{n}.{n}.{n+}
1.1.1 [Add Paragraph Text
Here]
A paragraph at the third level of your
content. You might indent paragraphs (or styles) using this format.
If so, paragraphs using this same format would be seen as "children" of
first-level and second-level paragraphs and numbered like this:
1.0
1.1
1.1.1
1.1.2
2.0
2.1
2.1.1
2.1.2
2.1.3
- 369 -
MADCAP FLARE
Auto-number format*
O:{R+}.
I. [Add Text Here]
A paragraph at the first level of an
outline. Additional paragraphs using
this same format would be numbered
like this:
II.
III.
IV.
O:{ }{A+}.
A. [Add Text Here]
A paragraph at the second level of an
outline. You might indent paragraphs
(or styles) using this format. If so, paragraphs using this same format
would be seen as "children" of firstlevel paragraphs and numbered like
this:
I.
A.
B.
II.
A.
B.
C.
- 370 -
Auto-number format*
CF: FIGURE {chapnum}{n+}:
FIGURE 1-1: [Add Figure
Caption Text Here]
A paragraph below an image to
describe the contents of the image. In
this example, the first number refers
to the chapter number where the
image is included, and the second
number simply increments by 1 each
time the auto-number format is
applied to content.
So the first few figure captions of
Chapter 1 would be numbered like
this:
FIGURE 1-1:
FIGURE 1-2:
FIGURE 1-3:
And the first few figure captions of
Chapter 2 would be numbered like
this:
FIGURE 2-1:
FIGURE 2-2:
FIGURE 2-3:
T:Table {n+} -
Table 1 - [Add Table Heading Text Here]
A paragraph above a table to display
the title of the table. In this example,
a chapter number is not included, so
the numbering would simply continue
across all chapters, like this:
Table 1 Table 2 Table 3 -
{n+}.
1. [Add Text Here]
A paragraph that is part of step-bystep procedures, which would look
like this:
1.
2.
3.
- 371 -
MADCAP FLARE
Auto-number format*
{R+}.
I. [Add Text Here]
A paragraph that is the first level of
an outline. In this example, we've
used uppercase Roman numerals for
the first level, so it would look like
this:
I.
II.
III.
*Single or double letters followed by a colon at the beginning of formats (e.g., GH:) are series labels, which are used to keep autonumber formats organized into groups. They may or may not be necessary, depending upon what you are trying to do.
** Portions in brackets are simply placeholders that we have included to indicate where you might add text next to an autonumber. They are not part of the actual auto-number format. - 372 -
Creating Auto-Number Formats For Styles
When you incorporate auto-numbering into content, you do so by creating an auto-numbering format, which consists of one or more commands. Some examples of commands are: CH:, {n+}, {chapnum}, {b}, and {/b}. In addition, you can add text next to commands.
E X AMPLE
Let 's say y ou want t o ap p ly au t o-nu mbering t o figu re cap t ions. Fu rt hermore, let 's
say y ou want t he beginning of each cap t ion t o cont ain t he word "Figu re" followed by
t he chap t er nu mber, a d ash, and t he next increment ed number (e. g. , Figu re 1-5, Figure 1- 6 , Figu re 1- 7). To accomp lish t his, y ou might creat e an au t o- nu mbering format t hat looks like t his: C H:Figu re {chap nu m}-{n+ }.
The following steps show you how to create an auto-number format for a style class. This is the recommended method. A style allows you to apply the same format to multiple paragraphs throughout
your project, and any changes to the format are applied automatically to all the paragraphs using
that style. Alternatively, you can create an auto-number format for a single paragraph. For steps see
the online Help.
You can perform this task in the Stylesheet Editor, using either the Simplified view or the Advanced
view. The following steps show you how to create auto-number formats with the Simplified view. For
steps on using the Advanced view, see the online Help.
How to create an auto-number format for a style using the Simplified view
1. Open the style sheet that you want to modify.
2. In the local toolbar, make sure the first button displays
(which means that the
Simplified view is currently shown in the editor). If the button displays
instead,
then click it.
3. In the upper-left corner of the editor, click in the Show Styles field
select Show Paragraph Styles.
and
4. On the left side of the Stylesheet Editor, select the style. Usually, it is a paragraph or heading
style (e.g., h1, p.Figure). If you do not yet have a style that you want to use, you can create
one.
5. In the local toolbar of the editor, click
6. Select the Auto-number tab.
- 373 -
MADCAP FLARE
7. (Optional) From the Available commands drop-down list, you can filter the auto-number
commands shown in the area below by selecting one of the options.
n
Show All Displays all of the commands in the area below.
n
Show AutoNumber Commands Displays only the auto-number commands in the
area below. These include commands such as chapter, section, and volume numbers;
counters; and series labels.
Chapter, section, and volume number commands ({chapnum}, {secnum}, {volnum})
let you organize your output into different areas and apply number sequences to them
(e.g., Chapter 1, Chapter 2, Chapter 3).
Counters are commands (such as {n}, {n=1}, {n+}, {r}, {A}, and {Gn}) that provide
information about what types of numbers should be used and how they should be incremented.
Series labels are prefixes to a format (comprised of one or two letters and a colon) that
provide a way to limit numbering sequences for different purposes. Although Flare
includes H: in the list of available commands, that is simply one example of a series
label. The letter that you use as a series label is arbitrary. You can replace H and
choose any letter of the alphabet, followed by a colon. The exception to this is a twoletter series label, in which the first letter represents a series that encompasses more
than just one topic. For example, CH is an example of a series label that applies across
an entire chapter. The H can be replaced with another letter, but you must keep the C
in order to use this command. Finally, it's important to note that a series label must
always be the first element in an auto-number format.
- 374 -
n
Show File Commands Displays only the file commands in the area below. These
include commands that let you incorporate different parts of a file (such as the file
name, file path, and file extension) in an auto-number format.
n
Show Format Commands Displays only the format commands in the area below.
These include commands such as {b}, {i}, {color red}, and {size 12pt}, which let you
determine how an auto-number format will look. Many of these commands require a
beginning command (e.g., {b}) and an ending command (e.g., {/b}). However, if you
plan to generate FrameMaker output from your project, you should not use these format commands, since they are not supported in FrameMaker. Instead, create and
apply a span class to the auto-number format to change its look. To create a span
class, open the Stylesheet Editor, select the span tag on the left side of the editor, and
follow the steps for creating a style (e.g., span.BoldGreen).
n
Show Page Commands Displays only the page commands in the area below. These
let you include the page number and count in an auto-number format.
n
Show Text Commands Displays only the text commands in the area below. These
commands let you incorporate text from an area of your output into the auto-number
format.
8. In the Enter format field, provide the auto-number format for the style. This format can be
a combination of text that you type and automated commands that you select. To add a command to the "Enter format" field, double-click it from the list in the area below.
E X AMPLE S
If y ou want t he au t o- nu mber t o inclu d e t ext (su ch as "Table" or "Figu re"),
simp ly t y p e it in t his field . You can also d ou ble- click any of t he command s
below t o ad d t hem t o t his field . For examp le, y ou might want t o ad d a cou nt er
t hat increment s t he au t o- nu mbers by one (e. g. , Figu re 1, Figu re 2, Figu re 3).
The command for t his is {n+ }. Descrip t ions for each command are d isp lay ed
in t he list .
Some command s inclu d e a st art t ag and an end t ag. For examp le, if y ou want
a p ort ion of t he au t o- nu mber format be d isp lay ed in bold , y ou wou ld p lace
y ou r cu rsor in t he "Ent er format " field where y ou want t o st art t he bold font
and d ou ble- click b in t he list below. Then p lace y ou r cu rsor where y ou want
t he bold font t o end and d ou ble-click /b from t he list .
So in t he end , y ou r au t o- nu mber format might inclu d e a combinat ion of t ext
and mu lt ip le command s, su ch as: {b}Table {n+ } - {/b}.
Following are descriptions of the commands that are available.
Auto-number commands:
n
{n} Retains the current counter value and displays it. You might use this command,
for example, if you are applying auto-number formats to multi-level paragraphs, where
one paragraph acts as the "parent" to another. Let's say the first-level paragraphs are
numbered like this: 1.0, 2.0, 3.0. If you want the second level paragraphs to keep the
first number of its parent paragraph and increment the second number (e.g., 1.1, 1.2,
1.3), you would enter the {n} command to continue displaying that first number,
which represents the parent paragraph (in this case, 1). For an example, see "AutoNumber Format Examples" on page 367.
n
{n=1} Resets the counter value to 1 and displays it. You can replace the number 1 with
any other number that you want to use.
n
{ =0} Resets the counter value to 0 but does not display it. You can replace the
number 0 with any other number that you want to use.
n
{n+} Increments the counter value and displays it. You might use this command, for
example, to increment a list of step-by-step procedures (e.g., 1., 2., 3.). For an example,
see "Auto-Number Format Examples" on page 367.
n
{} Retains the current value and does not display it. You might use this command, for
example, if you are creating an outline with Roman numerals at the first level and
uppercase alpha numerals at the second level. If you are creating the format for the second level, you want the auto-number format to keep track of the fact that it is a "child"
of the first level paragraph, but you do not want to display the Roman numeral from it
- 375 -
MADCAP FLARE
(e.g., IV.A.). Instead, you only want to display the uppercase alpha letter (e.g., A). In
order to do this, you would insert the { } command at the place where the Roman
numeral would normally be displayed. For an example, see "Auto-Number Format
Examples" on page 367.
n
{secnum} Displays the current section number. You can use this command if you are
creating online output, or Word, XPS, PDF, or XHTML output. This command does
not apply to FrameMaker output.
Note: To generate section numbers, you need to create an auto-number format
that includes the {secnum} command. Then you need to specify section breaks in
the outline TOC. For more information see the online Help or the Flare Printed Output Guide.
Note: You can also insert Section Number variables into page layout headers. By
doing this, you can automatically display the correct section number at the top or
bottom of pages in the output. For more information see the online Help or the
n
{chapnum} Displays the current chapter number. For an example, see "Auto-Number
Format Examples" on page 367.
Note: To generate chapter numbers, you need to create an auto-number format
that includes the {chapnum} command. Then you need to specify chapter breaks
in the outline TOC. For more information see the online Help or the Flare Printed
Output Guide.
Note: You can also insert Chapter Number variables into page layout headers. By
doing this, you can automatically display the correct chapter number at the top or
- 376 -
n
{volnum} Displays the current volume number. For an example, see "Auto-Number
Note: To generate volume numbers, you need to create an auto-number format
that includes the {volnum} command. Second, you need to specify chapter breaks
in the outline TOC. Third, you need to specify the auto-number flow for each volume, resetting the volume number to a specific number.For more information see
the online Help or the Flare Printed Output Guide.
Note: You can also insert Volume Number variables into page layout headers. By
doing this, you can automatically display the correct volume number at the top or
n
{r} This is the same as the {n} command, except it displays the counter as a lowercase
Roman numeral. You can replace the "n" with an "r" in any of the commands listed
above.
n
{R} This is the same as the {n} command, except it displays the counter as an uppercase Roman numeral. You can replace the "n" with an "R" in any of the commands
listed above. For an example, see "Auto-Number Format Examples" on page 367.
n
{a} This is the same as the {n} command, except it displays the counter as a lowercase
alpha letter. You can replace the "n" with an "a" in any of the commands listed above.
n
{A} This is the same as the {n} command, except it displays the counter as an uppercase alpha letter. You can replace the "n" with an "A" in any of the commands listed
above. For an example, see "Auto-Number Format Examples" on page 367.
n
{Sn} This is a counter to be used over the course of an entire section. This specific command retains the current counter value and displays it. However, you can modify it to
create custom versions of any of the commands that you see above with {n}. For example, you might want to use {Sn+} or {Sn=1}.
n
{Cn} This is a counter to be used over the course of an entire chapter. This specific
command retains the current counter value and displays it. However, you can modify
it to create custom versions of any of the commands that you see above with {n}. For
example, you might want to use {Cn+} or {Cn=1}.
n
{Gn} This is a counter to be used globally in your content. This specific command
retains the current counter value and displays it. However, you can modify it to create
custom versions of any of the commands that you see above with {n}. For example,
you might want to use {Gn+} or {Gn=1}.
n
H: Specifies a series labeled H. However, you can use any letter of the alphabet for a
series label, and you can use several different series labels throughout your content. For
example, you might want to use F: for a series of figure captions, or T: for a series of
table captions. If you use a series label, it must be first in the auto-number format. For
examples, see "Auto-Number Format Examples" on page 367.
- 377 -
MADCAP FLARE
n
SH: Specifies a section-wide series labeled H. However, you can use any letter of the
alphabet as the second letter (replacing H). For example, you might want to use SF: for
a section-wide series of figure captions, or ST: for a section-wide series of table captions. If you use a series label, it must be first in the auto-number format.
n
CH: Specifies a chapter-wide series labeled H. However, you can use any letter of the
alphabet as the second letter (replacing H). For example, you might want to use CF:
for a chapter-wide series of figure captions, or CT: for a chapter-wide series of table captions. If you use a series label, it must be first in the auto-number format. For an example, see "Auto-Number Format Examples" on page 367.
n
GH: Specifies a global series labeled H. However, you can use any letter of the alphabet
as the second letter (replacing H). For example, you might want to use GF: for a global
series of figure captions, or GT: for a global series of table captions. If you use a series
label, it must be first in the auto-number format. For an example, see "Auto-Number
File commands:
n
{ext} Displays the file extension.
n
{file} Displays the file name, including the extension.
n
{filename} Displays the file name, without the extension.
n
{path} Displays the path of the file.
n
{url} Displays the path of the file, URL syntax.
Format commands:
- 378 -
n
{b} Starts bold text.
n
{/b} Ends bold text.
n
{bg red} Starts new background color. You can replace "red" with another color.
n
{/bg} Ends the background color.
n
{color red} Starts new text color. You can replace "red" with another color.
n
{/color} Ends the text color.
n
{default} Resets all font changes.
n
{family Courier New} Starts a new font family. You can replace "Courier New" with
another font family.
n
{/family} Ends font family.
n
{i} Starts italic text.
n
{/i} Ends italic text.
n
{size 12pt} Starts font size. You can replace "12pt" with another font size.
n
{/size} Ends font size.
n
{sub} Starts subscript text.
n
{/sub} Ends subscript text.
n
{sup} Starts superscript text.
n
{/sup} Ends superscript text.
n
{u} Starts underline text.
n
{/u} Ends underline text.
Page commands:
n
{page} Displays the page number.
n
{pagecount} Displays the page count.
Text commands:
n
{title} Displays the title of the document (from the Properties dialog).
9. In the Position field, you can select the position for the auto-number format in the paragraph.
n
Inside Head The auto-number format is placed before the paragraph content, inside
the content area. Text that is wrapped to the next line will align under the autonumber format. n
Outside Head The auto-number format is placed before the paragraph content, but
outside of the content area. Therefore, text that is wrapped to the next line will align
under the previous text (not under the auto-number format). You can provide space
between the format and the content by using the "Offset" field. n
Inside Tail The auto-number format is placed after the paragraph content, inside the
content area. Text that is wrapped to the next line will align under the auto-number
format. n
Outside Tail The auto-number format is placed after the paragraph content, but outside of the content area. Therefore, text that is wrapped to the next line will align
under the previous text (not under the auto-number format). You can provide space
between the format and the content by using the "Offset" field. n
Float Left The auto-number format is placed to the left of the paragraph content, in
alignment with the left side of the page frame.
n
Float Right The auto-number format is placed to the right of the paragraph content,
in alignment with the right side of the page frame.
n
Outside Frame The auto-number format is placed outside the page layout frame
holding the paragraph.
n
Outside Frame (Left Side) The auto-number format is placed to the left of the page
layout frame holding the paragraph.
n
Outside Frame (Right Side) The auto-number format is placed to the right of the
page layout frame holding the paragraph.
- 379 -
MADCAP FLARE
n
None The auto-number functionality (auto-numbers, counters, and formatting) are
removed from the class, while the other class properties are preserved. 10. In the Offset field, you can specify the amount of space that you want to create between a format's content and the paragraph content. Select Length in the top drop-down list. You can
then enter an amount and choose from several different units of measurement (points, pixels,
centimeters, etc.). Click OK when you are done.
11. In the Span Class field, you can enter a span style class for the auto-number format. Use
this field instead of format commands (such as {b} and {i}) if you are planning to create
FrameMaker output. You can create and modify span classes in the Stylesheet Editor. To
create a span class, open the Stylesheet Editor, select the span tag on the left side of the
editor, and follow the steps for creating a style (e.g., span.BoldGreen).
12. In the Properties dialog, click OK.
- 380 -
to save your work.
Fonts
Following are some ways that you can work with fonts in Flare. For more information see the online
Help or the Flare Styles Guide.
n
Selecting fonts You can select fonts to be applied to your content. This can be done through
the use of styles or with local formatting. As always, using a style is recommended when possible.
n
Editing font properties You can modify various properties for fonts. This includes changing the font family, size, style, color, and more. You can set these properties by using styles or
locally by highlighting the text and selecting Format>Font. Using styles is recommended.
For more information about using styles, including steps, see the online Help or the Flare
Styles Guide. For basic information about styles in this manual, see "Styles and Style Sheets"
on page 362.
n
Creating font sets You can define and apply a font set. A font set (or font family) is just
what it sounds like—a collection of fonts. You can create a font set in order to designate
"backup" fonts to be used in case the preferred font is not available on the user's computer. If
the first (preferred) font family in the set is not found on the user's computer, the second font
family in the set is used. If the second font family is not found, the third font family is used,
and so on.
n
Selecting a font family list You can customize the Flare user interface to show only the
font families that you specify. This is a way of limiting the list of fonts to those that you use
the most and hiding from view those that you do not use.
- 381 -
MADCAP FLARE
Headings
When you are creating headings in print-based output, you have a lot of options as to how you can
configure them. You can simply use the <h1> through <h6> style tags provided in Flare, and you
can modify the style settings to meet your needs.
Following is a topic shown in Print Layout mode with multiple headings. Each heading was configured differently to affect how it is displayed on the page.
For more information, including steps for creating each heading example, see the online Help or the
- 382 -
Lists
Flare lets you work with numbered and bulleted lists in a variety of ways, such as the following.
n
Simple lists You can create simple lists that are numbered or bulleted. See "Creating Simple
Lists" on page 385.
n
Multi-level lists You can create numbered and bulleted lists with multiple levels (such as
an outline). There are multiple ways to create a multi-level list. See "Creating Multi-Level
Lists" on page 386.
n
Continue sequence Use this to ensure that the next list you create in the topic starts with
the next number in the sequence of the list above (even if the two lists are separated by other
content). See "Continuing the Sequence of Lists" on page 389.
n
Merge Use this to combine a list with another list immediately before it. See "Merging Lists"
on page 390.
n
Notes or comments (paragraph item) Use this to include comments between items without interrupting the flow of the list. See "Adding Notes or Comments Between List Items" on
page 392.
n
Restart numbering Use this to specify a number to start a numbered list, or to start a
selected item within a numbered list. See "Restarting Numbering in Lists" on page 396.
n
Reverse Use this to reorder the items in a list so that they appear in reverse order (i.e., first
item is last, last item is first). See "Reversing Lists" on page 397.
n
Sort Use this option to reorder the items in a list alphabetically. See "Sorting Lists" on page
398.
n
Unbind (remove) Use this to remove the list designation from the content so that it displays as regular text. See "Unbinding Lists" on page 399.
n
Edit list styles You can modify the look of lists by making adjustments to the tags and
style classes used for them. By editing list styles, you can affect things such as the alignment,
background, bullet images, and indentation of lists. For more information see the online Help
or the Flare Styles Guide.
- 383 -
MADCAP FLARE
Quick List Drop-Down Menu
The easiest way to create a numbered or bulleted list is to use Flare's quick drop-down menu button
in the Text Format toolbar (View>Toolbars>Text Format), from which you can select various
list formats. The image on the button depends on the most recent action that you have used. You
can click the image to quickly apply that type of list format to the selected content. Otherwise, you
can click the down arrow and select one of the other list formats available.
Inserts a bullet list.
Inserts a circle bullet list.
Inserts a square bullet list.
Inserts a numbered list.
Inserts a lower alpha numbered list.
Inserts an upper alpha numbered list.
Inserts a lower Roman numbered list.
Inserts an upper Roman numbered list.
Note: You can also set the bullet type on a style. This includes selecting any of the types mentioned, plus more.
- 384 -
Creating Simple Lists
You can create simple lists that are numbered or bulleted.
Numbered:
1. Step one.
2. Step two.
3. Step three.
Bulleted:
n
Item one.
n
Item two.
n
Item three.
How to create a simple list
n
Highlight existing text to which you want to apply a list format.
OR
n
Place your cursor in the topic where you want to apply a list format.
n
If you want to quickly apply the most recent list format, click the list button on the
Text Format toolbar. For example, if the most recent list format used was lowercase
alpha, the button will look like this:
. If you click the button, the lowercase alpha
format will be applied. (To open the Text Format toolbar, click
or select View>Toolbars>Text Format.) OR
n
Click the down arrow of the list button
and select a format.
OR
n
Select Format>List. Then select the format from the list.
4. (Optional) After providing the content for a list item, press Enter.
The list item is automatically applied to the next line. To remove the list format from a line,
simply click the list button again.
to save your work.
- 385 -
MADCAP FLARE
Creating Multi-Level Lists
You can create multi-level lists that are numbered, bulleted, or both.
Numbered:
1. Step one.
a. Substep one.
b. Substep two.
2. Step two.
3. Step three.
Bulleted:
n
Item one.
l
Subitem one.
l
Subitem two. n
Item two.
n
Item three.
Numbered and bulleted:
1. Item one.
l
Subitem one.
l
Subitem two. 2. Item two.
3. Item three.
- 386 -
How to create a multi-level list using indentation
1. Follow the steps for creating a simple list, with all of the list items at the same level.
2. Select the line items to be indented.
E X AMPLE
You may want t he first lev el t o cont ain regu lar nu mbers (1, 2, 3) and t he second lev el t o hav e lowercase alp ha nu mbering (a, b, c). If t his is t he case,
select t he line it ems t hat will u se a, b, c, and so on.
3. Click
. The line items are indented.
n
Click the down arrow of the list button
and select a format.
OR
n
Select Format>List. Then select the format from the list.
to save your work.
How to create a multi-level list using styles
1. Open the appropriate style sheet, select the li tag from the list of styles, and create as many
classes as you need.
E X AMPLE
You might want t o creat e a st y le t hat is called "Nu mberInd ent ed " (i. e. , li. Nu mberInd ent ed ), wit h t he "margin-left " v alu e of t he Box p rop ert y grou p set at
20 p t . May be y ou wou ld set t he "list - st y le- t y p e" v alu e (in t he List p rop ert y
grou p ) t o "u p p er-alp ha. "
In ad d it ion t o t his, y ou might want anot her st y le called "Nu mberInd ent ed 2, "
wit h t he "margin-left " v alu e set at 4 0 p t . Perhap s t he "list -st y le-t y p e" set t ing
for t his st y le is set at "lower-roman. "
Note: Different browsers may treat margin and padding settings differently. For example,
Internet Explorer 8 and Firefox honor padding settings more than they honor margin settings. If you were to set a left margin at, say, 1 inch, Internet Explorer 7 would show it
that way. However, in order to get the same results in Internet Explorer 8 or Firefox, you
would also need to set the left padding at 1 inch.
2. Open the content file (e.g., topic, snippet) and follow the steps for creating a simple list, with
all of the list items at the same level initially.
3. Select the items that you want to move to another level and apply the appropriate list style
that you created.
to save your work.
- 387 -
MADCAP FLARE
For more information about using styles, including steps, see the online Help or the Flare Styles
Guide. For basic information about styles in this manual, see "Styles and Style Sheets" on page 362.
- 388 -
Continuing The Sequence Of Lists
If you have created multiple lists in a topic, you can continue the sequence from one to the other.
This ensures that the next list you create in the topic starts with the next number in the sequence of
the list above (even if the two lists are separated by other content).
E X AMPLE
Let 's say y ou hav e a nu mbered list from 1 t o 10 at t he t op of y ou r t op ic and y ou ad d
a few regu lar p aragrap hs (not in a list ) aft er it . If y ou st art anot her nu mbered list
and select t his op t ion, t he new list will st art at 11. How to continue the sequence of lists
a. If the tag block bars are not shown to the left of the content, click
the editor.
at the bottom of
b. Right-click the ol or ul tag bar of the lower list (where you want to continue the numbering).
c. In the context menu, select Continue Sequence.
OR
a. Place your cursor somewhere in the lower list (where you want to continue the numbering).
b. Click the down arrow next to the List Actions button
.
This button is located on the Text Format toolbar. If you do not see this toolbar, select
View>Toolbars>Text Format.
c. Select Continue Sequence.
to save your work.
- 389 -
MADCAP FLARE
Merging Lists
There may be times when you are creating lists and find that you have two or more ordered lists
(<ol> tags) or unordered lists (<ul> tags) next to each other. If necessary, you can quickly merge the
lists together into one list.
E X AMPLE
Let 's say y ou hav e t wo nu mbered list s, wit h each list rest art ing at nu mber 1.
You can make t he nu mbering cont inu ou s in t hose t wo list s by merging t hem.
- 390 -
How to merge lists
the editor.
at the bottom of
b. Right-click the ol or ul tag bar of one of the lists.
c. In the context menu, select either Merge With Previous List or Merge With
Next List. The lists are merged.
OR
a. Place your cursor somewhere in one of the lists.
.
c. Select either Merge With Previous List or Merge With Next List. The lists are
merged.
to save your work.
- 391 -
MADCAP FLARE
Adding Notes Or Comments Between List Items
After creating a simple or multi-level list, you may want to include comments between items without interrupting the flow of the list. You can do this by using paragraph items in a list.
Here is a typical list with the tag bars shown to the left of the content. Notice that the entire list has
an <ol> tag, and each line in the list has an <li> tag.
Each time you press Enter after a line, a new <li> tag is created.
Let's say that we want to add two comments after #2. By turning #2 into a paragraph item, a <p>
tag is added after the <li> tag in that line, and in each line that you create immediately after that
line.
- 392 -
The paragraph item icon
is displayed at the beginning of the final paragraph item in that <li>
tag. If you click this icon, that line becomes a new list item with its own <li> tag and a number (or
bullet, if used) is displayed before it. For example, if we were to click the item in the previous image,
the resulting list would look as follows.
- 393 -
MADCAP FLARE
How to add paragraph items in a list
the editor.
at the bottom of
b. Right-click on the li tag bar that is next to the item where you want to add a paragraph item.
c. In the context menu, select Make Paragraph Item(s). A <p> tag is added after the
<li> tag.
OR
a. Click in the list where you want to add a paragraph item.
. This button is located on
the Text Format toolbar. If you do not see this toolbar, select View>Toolbars>Text
Format.
c. Select Make Paragraph Item(s). A <p> tag is added after the <li> tag.
OR
a. Click in the list where you want to add a paragraph item.
b. On your keyboard hold down the CTRL key and press the semicolon key (CTRL+;). A
<p> tag is added after the <li> tag.
3. To add lines without a number or bullet, simply press Enter on your keyboard and type your
content.
4. To continue the numbering or the bullets, click the paragraph item icon
simply starts another <li> tag.
- 394 -
to save your work.
. Doing this
How to return a paragraph item in a list to a simple item
the editor.
at the bottom of
b. Right-click on the li tag bar that is next to a line where a paragraph item exists (an
<li> tag followed by a <p> tag).
c. In the popup, select Make Simple Item(s). The <p> tag is removed.
OR
a. Click in the list where a paragraph item exists (an <li> tag followed by a <p> tag).
. This button is located on
the Text Format toolbar. If you do not see this toolbar, select View>Toolbars>Text
Format.
c. Select Make Simple Item(s). The <p> tag is removed.
to save your work.
- 395 -
MADCAP FLARE
Restarting Numbering In Lists
You can create a numbered list in a topic by using the Numbered List button
in the Text Format toolbar or by using the Format>List menu. But what if you need to restart the list at a specific
number? The following steps show you how to do this.
How to restart numbering in a list
2. Click in the numbered list where you want to restart the numbering.
3. In the Text Format toolbar, select the down arrow in the Assorted List Actions button
.
If the Text Format toolbar is not open, select View>Toolbars>Text Format.
Alternatively, you can select Format>List>List Actions.
4. Do one or both of the following:
n
If you want to change the numbering for the entire list, restarting the first item at a specific number, enter the desired number in the List Start # section and click the Enter
button .
n
If you want to change the numbering for a specific item in a numbered list, enter the
desired number in the Item # section and click the Enter button .
E X AMPLE
Let 's say y ou hav e a nu mbered list from 1 t o 10. If y ou were t o click in
t he p aragrap h wit h t he nu mber 7 and t hen u se t his op t ion t o st art nu mbering at 23, y ou r list wou ld change so t hat t he nu mbering d isp lay ed as
1 t o 6 and t hen 23 t o 26 .
- 396 -
to save your work.
Reversing Lists
After you have created a list, you can reorder the items in the list so that they appear in reverse
order (i.e., first item is last, last item is first). How to reverse a list
the editor.
at the bottom of
b. Right-click the ol or ul tag bar of the list.
c. In the context menu, select Reverse List.
OR
a. Place your cursor somewhere in the list.
.
c. Select Reverse List.
to save your work.
- 397 -
MADCAP FLARE
Sorting Lists
After you have created a list, you can reorder the items in the list alphabetically. How to sort a list
the editor.
at the bottom of
b. Right-click the ol or ul tag bar to the left of the list.
c. In the context menu, select Sort List.
OR
.
c. Select Sort List.
- 398 -
to save your work.
Unbinding Lists
If you have created a list and no longer want the content to be displayed in a list, you can unbind it.
This removes the list designation from the content so that it displays as regular text. How to unbind a list
the editor.
at the bottom of
b. Right-click the ol or ul tag bar to the left of the list.
c. In the context menu, select Unbind List.
OR
.
c. Select Unbind List.
to save your work.
- 399 -
MADCAP FLARE
Object Positioning
After you insert an object (such as an image or text box) into a topic, you can adjust its positioning
on the page. This can be done through styles or by using local formatting.
Floating Objects
One way to position an object is to "float" it to the left or right on a page. When you float an object
to the left, wraparound text can flow on the right side of the object. When you float an object to the
right, wraparound text can flow on the left side of the object. You can also float objects outside of
the frames where the normal text flow occurs.
- 400 -
- 401 -
MADCAP FLARE
For more information see the online Help or the Flare Styles Guide.
- 402 -
You can affect the look and behavior of paragraphs in various ways. These settings can be applied
locally or to the style used for the paragraph. Modifying the style is typically preferable to changing
the settings locally for a single paragraph. For more information about each of the following, including steps, see the online Help or the Flare Styles Guide.
Following are some of the more common ways that you can format paragraphs.
n
Alignment You can format a paragraph so that the text is aligned right, left, centered, or justified.
n
Auto-numbering You can apply an auto-number format to paragraphs so that certain content and/or incremented numbering displays with it. This is useful for numbering elements
such as chapters, figures, or tables.
n
Background You can set a background color and/or image on a paragraph.
n
Borders You can add borders around a paragraph. Borders can be added on any side of a
paragraph (left, right, top, bottom), or all around it.
n
Drop caps/initial caps You can create an effect on a paragraph so that the initial letter is
different than the others and drops down to the lines below.
n
Hyphenation You can specify whether words at the end of a line in a paragraph should be
hyphenated before continuing to the next line. You can also determine minimum word and
character settings to be used for hyphenation.
n
Indentation You can indent paragraphs so that they start or end at a certain distance from
the left or right side of the window or page frame.
n
Line spacing You can specify the amount of spacing between lines in a paragraph.
n
Moving paragraphs You can move paragraphs and other block content (e.g., lists, images)
around through the use of structure bars.
n
Next style You can specify that a particular style should be used when you press Enter at
the end of the current style. For example, after you type text for a heading and press Enter,
you might want the next style to be something like p.TopicText, rather than the main <p>
tag.
n
Page and column breaks You can apply a page or column break to a paragraph or heading. For example, you might do this if you want the paragraph or heading to start at the
beginning of the next page or column. This feature is used for print-based output.
n
Positioning You can adjust the positioning of a paragraph. For example, you can float it to
the left of the page layout frame. You can do this by applying a position setting on the style
used by the paragraph.
n
Short line elimination You can use this feature to automatically adjust word spacing if
the last line of a paragraph is only a certain number of characters long. Therefore, the spacing
may be widened to make the last line longer, or the spacing may be narrowed to bring the
words in the last line up to the previous line.
n
Spacing above/below You can set the amount of spacing above and below paragraphs.
- 403 -
MADCAP FLARE
n
- 404 -
Widow and orphan control You can use widow and orphan control to avoid instances
where "leftover" lines from a paragraph are shown at the top or bottom of a page or column.
This feature is used for print-based output.
Skins
A skin is a file that contains information about the appearance of an online output window. A skin
helps to determine:
n
How big the output window should be and where it should be positioned on the user's screen
n
Settings that are specific to certain kinds of output types (i.e., browser-based Help and HTML
Help)
n
Which online Help tabs or accordions (e.g., TOC, index, search) are included in the output
and which one should be the default element (the one that is active when users first access
the output)
n
And other settings…
There are two kinds of skins—Standard skins
for WebHelp, WebHelp Plus, WebHelp AIR, DotNet Help, and HTML Help outputs; and WebHelp Mobile skins
for WebHelp Mobile output.
Steps For Using Skins
Following are the basic steps for using skins in Flare.
1. Add skin Depending on the project template you select, Flare may provide you with an initial skin in your project. However, you might decide to add more skins to the project so that
you have different skins for different targets. Each skin in a Flare project uses a skin type,
which is associated with a skin template. The Skin Editor displays only settings relevant to
the skin type (Standard or WebHelp Mobile). See "Adding Skins to a Project" on the next
page.
2. Open skin After you add a skin to your project, it is stored in the Project Organizer under
the Skins folder. At any time, you can open a skin to work on it. See "Opening Skins" on page
408.
3. Edit skin After you open a skin, you can edit its settings in order to change the appearance
of the output window. See "Editing Skin Settings" on page 409.
4. Associate skin with target Now that you have modified the skin, you need to associate it
with the target you are building. See "Associating Skins with Targets" on page 412.
Note: You can download a variety of free skins with different looks from the MadCap Software
website. Simply go to:
http://madcapsoftware.com/downloads/utilities/flareskingallery.aspx
After downloading the skin, you can import it into your project. For more information see the
online Help.
- 405 -
MADCAP FLARE
Adding Skins To A Project
Flare may provide you with an initial skin in your project. You can open this skin, edit its settings,
and associate it with any targets you want to build. However, you might decide to add another skin
to the project so that you have different skins for different targets.
How to add a skin to a project
1. Select Project>Add Skin.
The Add Skin dialog opens.
n
n
There are two skin types—"Standard" (which is used for most online output types) and "WebHelp Mobile" (which is used for WebHelp Mobile output). One of these two skin types is associated with each skin template. Just choose a template using a skin type that is most
appropriate for your output.
- 406 -
3. In the File Name field, type a new name for the skin.
4. Click Add.
5. Click OK.
The skin is added to the Skins folder in the Project Organizer. The Skin Editor opens to the
right. The Skin Editor displays only settings relevant to the selected skin type.
- 407 -
MADCAP FLARE
Opening Skins
After you add a skin to your project, it is stored in the Project Organizer under the Skins folder. At
any time, you can open a skin and edit its settings in the Skin Editor.
How to open a skin
2. Double-click the Skins folder.
The skin(s) in your project are displayed.
3. Double-click the skin that you want to open.
The Skin Editor opens to the right.
- 408 -
Editing Skin Settings
After you add a skin to your project (Project>Add Skin), you can open it and edit its settings in
the Skin Editor to meet your needs. The skin settings help determine the look and feel of your output window when you build a target.
There are various skin editing tasks for the different online output types in Flare (DotNet Help,
HTML Help, WebHelp, WebHelp Plus, WebHelp AIR, WebHelp Mobile). The primary tasks that you
can perform are listed below. There are two kinds of skins—Standard skins
for WebHelp, WebHelp Plus, WebHelp AIR, DotNet Help, and HTML Help outputs; and WebHelp Mobile skins
for WebHelp Mobile output. For detailed steps on each of these, see the online Help.
Tasks for all online output types (DotNet Help, HTML Help, WebHelp, WebHelp Plus,
WebHelp AIR, WebHelp Mobile)
n
Styles For certain elements of the online output window (e.g., navigation pane, TOC or
Mobile skins
to make changes for WebHelp Mobile output.
n
Tabs/accordions/links You can determine which navigation elements from your project
(TOC, Index, Search, Glossary, Browse Sequences, Favorites) that you want users to have
access to in the output. If you are creating HTML Help output, these elements will display as
tabs in the output window (except for a glossary, which is included in the TOC as a book). If
you are creating DotNet Help, WebHelp, WebHelp Plus, or WebHelp AIR, these elements will
display as accordion items in the output window. If you are creating WebHelp Mobile output,
the elements will display as simple links.
n
Topic toolbars In addition to the regular toolbars that can be included in all online outputs
(via the Help Viewer or through the use of skins), you have another option for including toolbars. This option lets you insert toolbars anywhere in any topics.
Tasks for DotNet Help, HTML Help, WebHelp, WebHelp Plus, and WebHelp AIR outputs only
n
Size/positioning You can set the size and position of the output window. The size refers to
the height and width of the output window. The position refers to the distance that the output window is placed from the top, bottom, left, and right of the user's computer screen.
n
Synchronize You can customize your output so that users can always see where the current
topic belongs in the table of contents (TOC), even if they did not access the topic via the TOC.
This can be done by selecting the "Automatically Synchronize TOC" option in the Skin Editor.
When users navigate from topic to topic in the output, the TOC automatically changes accordingly, highlighting the topic that is open.
Tasks for DotNet Help, HTML Help, WebHelp, WebHelp Plus, and WebHelp Mobile
outputs only
n
Preview You can see how your skin settings look in each of the online output types.
- 409 -
MADCAP FLARE
Tasks for DotNet Help, HTML Help, WebHelp, and WebHelp Plus outputs only
n
Feedback comments Users can enter comments on your Help topics. These comments may
be viewed (and replied to) by all other users viewing the output.
n
Feedback profile fields When your end users attempt to submit Feedback comments in
your output for the first time, they must first register by completing the Create Feedback Service Profile dialog (unless you enable anonymous comments for your output via Feedback
Explorer). In your Flare skin, you can customize that Create Feedback Service Profile dialog,
including which fields end users must complete and the way it looks. Two fields are always
required in the Create Feedback Service Profile dialog—Username and Email. In addition to
those fields, you can choose from several others to add, such as name, address, fax, department, and more.
Tasks for HTML Help only
n
Buttons You can select the Help buttons that you would like to include in the output window (e.g., Hide, Forward, Back, Print, customized buttons).
n
Index - binary You can create a binary index for your project. Binary indexes are intended
for merging multiple CHM files when you build a target. The index keywords in the CHM files
are sorted alphabetically and numerically for display in the output.
n
Index - bookmarks If you want index term links to point to the exact spot in the topic
where the index marker has been set, you need to specify this in the Skin Editor. Otherwise,
the index term links will point to the topic in general. However, by pointing to the individual
index markers, the index may not display the way you want if the index term points to multiple topics and you also have created a binary index. In other words, index entries pointing
to multiple topics will display the index terms repeated instead of the topic title. A workaround is to deselect the binary index option in the Skin Editor. However, keep in mind that
a binary index is required if you want to merge CHM files.
n
Navigation pane You can specify navigation pane settings for HTML Help output. This
includes setting the width of the navigation pane and determining whether it shown or hidden under different circumstances. The navigation pane is used to hold elements such as
TOCs and indexes.
n
TOC - binary You can create a binary table of contents (TOC) for your project. Binary TOCs
are intended for very large compiled Microsoft HTML Help projects, reducing the amount of
time it takes to load a TOC.
n
TOC - look You can specify the look and feel of your table of contents (TOC). This includes
adding plus/minus squares next to entries, changing the book/folder icons, adding border
around the TOC, and more.
n
Toolbar You can add a Web toolbar that displays at the top of each topic. This toolbar is
added automatically if you have enabled MadCap Feedback in the target, but you can add the
toolbar manually in the Skin Editor, even if you are not using MadCap Feedback.
- 410 -
Tasks for HTML Help, WebHelp, WebHelp Plus, WebHelp AIR, and WebHelp Mobile
outputs only
n
About box You can select a picture to be used for the "About box" in the output window. You
can use this About box for any purpose you like.
n
Caption You can enter the caption that you want to be used at the top of your online Help
window (e.g., in the title bar of the browser window or HTML Help viewer).
Tasks for HTML Help, WebHelp, WebHelp Plus, and WebHelp AIR outputs only
n
Toolbar settings You can specify toolbar settings for WebHelp, WebHelp AIR, WebHelp
Plus, and HTML Help output. This includes determining which buttons are displayed in the
toolbar. You can also add custom JavaScript for the toolbar.
Note: Although you cannot specify buttons for DotNet Help in the regular toolbar
(because the buttons are automatically included in the DotNet Help Viewer), you can specify buttons for customized topic toolbars in DotNet Help output.
Tasks for WebHelp, WebHelp Plus, and WebHelp AIR outputs only
n
Accordion title You can exclude the accordion title from output. This shifts the navigation
buttons to the left.
n
Navigation link - standalone topics You can add a navigation link to the top or bottom
of topics in WebHelp, WebHelp Plus, or WebHelp AIR outputs. This navigation link will not
display unless the output topic is opened as a standalone (outside of the main navigation
framework of the Help system). By clicking the link, a user can view the standalone topic in
the main navigation framework.
n
Navigation pane You can specify navigation settings for WebHelp, WebHelp Plus, or WebHelp AIR output. The navigation pane is used to hold the TOC, Index, Search, Glossary,
Browse Sequences, and Favorites in an accordion-type structure.
Tasks for WebHelp and WebHelp Plus outputs only
n
Browser settings You can specify which features will be used in the output window when a
browser is involved.
n
Comments - bottom of topics If you want MadCap Feedback comments to be displayed
automatically at the bottom of each WebHelp or WebHelp Plus topic, you can specify this in
the Skin Editor.
Tasks for WebHelp Mobile outputs only
n
Display number of items Because a mobile device is quite small, a user sometimes cannot
see all of the information normally seen in one of the other online outputs. When a user opens
a TOC, browse sequence, or index, it is not immediately apparent in mobile output how many
items are associated with a particular entry. Therefore, Flare lets you specify that the number
of items associated with each entry should be shown.
- 411 -
MADCAP FLARE
Associating Skins With Targets
After you add a skin to your project and edit the settings, you need to associate it with a target.
After you build the target, the output will be displayed in the skin. This task is necessary only for
online output.
How to associate a skin with a target
2. On the General tab of the Target Editor, click the drop-down arrow in the Skin field and
select the skin that you want to associate with the target.
- 412 -
to save your work.
In Flare you can determine what kind and how many types of output you want to provide for your
end users. This can involve different tasks, depending on what you want to accomplish.
Important Concepts
414
Tasks Associated with Outputs
417
Determining the Output Type
419
Changing the Output Type for a Target
432
Adding Targets
433
Renaming Targets
435
Setting a Primary Target
436
437
439
Applying Condition Tags to Content
441
Associating Condition Tags with Targets
447
448
- 413 -
MADCAP FLARE
Important Concepts
Following are some of the more important concepts for developing output.
Output Type
There are several types of online output (DotNet Help, HTML Help, WebHelp, WebHelp Plus, WebHelp AIR, WebHelp Mobile) and several types of direct print-based output (Adobe PDF, XHTML,
Microsoft XPS, Microsoft Word, Adobe FrameMaker) that you can produce in Flare. There is also an
output type that lets you generate DITA code from your project (DITA code can be used to create
either online or print-based output). Each output type has its own set of advantages.
There is a fine line between what is called "online output" and what is called "print-based" output.
The truth is that topics in virtually any of Flare's online output types can be sent to a printer (and
therefore considered "print-based"). Similarly, any of the print-based output types can be viewed electronically (and therefore considered "online"). The real distinction between online and print-based
outputs has to do with their primary purpose. Online outputs are usually intended to be viewed on
a screen, rather than on a printed page. The idea is to show only small pieces of content at a time
and allow users to jump around to other topics or elements of the output. On the other hand, printbased output follows a more traditional format that you would find in an actual book or manual—
with the pieces of the output following one after the other on pages until the end of the book (e.g.,
title page, table of contents, preface, chapters, index, appendixes—with page numbers, as well as
header or footer content, shown along the way).
Target
It is easy to confuse output types with targets, but they are two different concepts. A target is one
instance of an output type. When you build your final output, you are essentially building one or
more of the targets in your project.
By default, when you create a new project using one of Flare's factory templates, one new target is
added to your project—depending on the format that you selected for your primary target.
However, this target is just a starting point for you. You can rename it to reflect the nature of your
project. For example, if you are writing a Help system for a software program called DoohickeyPro,
you could rename the default target to "DoohickeyPro." Also, just because only one target was added
when you first created the project, this does not mean that you are limited to just that target in your
project. You can add as many new targets as you need, using any of the available formats. You can
also make as many copies of an existing target as you want. Each target has properties that you
adjust to change the way the target behaves, as well as the way it looks and feels.
- 414 -
Primary Target
You can have as many targets in your project as you want, and any of your targets can be built (generated) whenever you like. However, chances are that you will have one target that you work with
more than the others. You can set it as your primary target.
A primary target is treated just like any of your other targets, with one exception. There are certain
shortcuts in Flare that let you build, view, or publish your primary target more quickly.
Primary target shortcuts:
n
Build the primary target (click
n
View the primary target (click
n
Publish the primary target (click
or press F6)
or press SHIFT+F6)
press CTRL+F6)
Condition Tags
Condition tags are markers that you can apply to different files or areas of your content so that some
sections show up in some of your outputs but not in others.
E X AMPLE
Let 's say y ou hav e t wo d ifferent au d iences—beginners and ad v anced u sers. The cont ent in y ou r p roject is t he same in most p laces for bot h au d iences. Howev er, t here
are sect ions t hat ap p ly only t o t he beginners, and ot her sect ions t hat ap p ly only t o
t he ad v anced u sers. You can u se one cond it ion t ag t o mark t he sect ions for t he
beginners only , and y ou can u se anot her cond it ion t ag t o mark t he sect ions for
ad v anced u sers only . This let s y ou creat e one ou t p u t for t he beginners and anot her
ou t p ut for t he ad v anced u sers wit hou t hav ing t o creat e t wo sep arat e p roject s.
For more information see "About Condition Tags" on page 437.
- 415 -
MADCAP FLARE
Single-Sourcing
"Single-sourcing" is a fancy term that means something very simple—to produce multiple results
from one source. In Flare, you can make use of single-sourcing in many different ways.
One way to single-source content is to take advantage of multiple output formats and condition
tags. How does it work? Each target in your project is a potential output (using a specific output format, such as DotNet Help or WebHelp). You can create and apply condition tags to content. Then
you associate the condition tags to your different targets as necessary, so that some content appears
in some targets but not in other targets. This way, you do not need to create a separate project for
each output that you want to produce. If most of the content for your outputs is similar, there is no
need to rewrite it in another project. Simply specify which sections to include or exclude in which targets through the use of condition tags. This is one reason that topic-based authoring is so appealing. By placing condition tags on individual topic files themselves, you can pick and choose which
topics to include in some outputs and which to include in other outputs.
You can also single-source images. If you have MadCap Capture installed and use it to create
images for your project, you can provide one group of settings for online outputs and another group
of setting for print-based outputs. You can do this from just one image, and you do not need to use
condition tags for it.
For more information, including other methods for single-sourcing content, see the online Help.
- 416 -
Tasks Associated With Outputs
When developing outputs through the use of targets, there are many possible tasks that you might
perform, depending on your situation. You may not need to perform all of the following tasks—just
those that fit your needs. You also may not necessarily perform these tasks in the following order.
n
Determine output type The first task in developing output for your project is to determine
which type of output is most appropriate for your needs. You might even need to produce
multiple outputs and require more than one output type. There are several types of online output (DotNet Help, HTML Help, WebHelp, WebHelp Plus, WebHelp AIR, WebHelp Mobile)
and several types of direct print-based output (Adobe PDF, XHTML, Microsoft XPS, Microsoft
Word, Adobe FrameMaker) that you can produce in Flare. There is also an output type that
lets you generate DITA code from your project (DITA code can be used to create either online
or print-based output). Each output type has its own set of advantages. The output type can
be specified on the General tab of the Target Editor. See "Determining the Output Type" on
page 419 and "Changing the Output Type for a Target" on page 432.
n
Add or make copies of targets Every target in a project has particular output type
assigned to it. You can add multiple targets to a project, and you can make as many copies of
existing targets that you want. For example, your project might end up containing three targets that are all based on the WebHelp output type. You can add targets by selecting
Project>Add Target. After you add a target, it is stored in the Targets folder in the Project
Organizer. See "Adding Targets" on page 433.
n
Rename targets It is helpful to rename targets that you use to reflect the nature of your
project (especially if you are using multiple targets with the same output type). To rename a
target, open the Targets folder in the Project Organizer, right-click the target you want to
rename, and then select Rename. Then type a new name for the target and press Enter. See
"Renaming Targets" on page 435.
n
Set primary target You can select a primary target when you are in the process of creating
a new project. Otherwise, you can open the Targets folder in the Project Organizer, rightclick the target that you want to specify as the primary, and select Make Primary. See "Setting a Primary Target" on page 436.
n
Create condition tags If you are creating multiple outputs from the same project and you
want the various outputs to contain different content, you can create condition tags. To create
a condition tag, you can open the Conditional Text folder in the Project Organizer, doubleclick a condition tag set, and click the New Item button
in the Condition Tag Set Editor.
See "Creating Condition Tags" on page 439.
n
Apply condition tags After you create condition tags, you can apply them to content. There
are many ways to apply condition tags, depending on the element you are working on. For
example, you can highlight text in a topic and select Format>Conditions. In the Condition
Tags dialog, you can select the condition tag(s) to be applied to that content. See "Applying
Condition Tags to Content" on page 441.
n
Associate condition tags with targets After creating and applying condition tags, you
need to tell Flare what your target should do with the condition tags that you have created
and applied. Should content with a particular condition tag be included in or excluded from
- 417 -
MADCAP FLARE
that target? To associate condition tags with a target, open the Targets folder in the Project
Organizer, and double- click the target that you want to open. Then in the Target Editor,
select the Conditional Text tab and click the appropriate check boxes next to the condition
tags that you want to include in that target or exclude from it. See "Associating Condition
Tags with Targets" on page 447.
n
- 418 -
Edit target settings Using the Target Editor, you can perform tasks such as changing the
output type, setting the output file name, selecting a master style sheet, improving the processing performance of the target, and more. To edit target settings, open the Targets folder
in the Project Organizer, double-click the target that you want to edit, and use the various
tabs in the Target Editor to specify settings. See "Editing Target Settings" on page 448.
Determining The Output Type
Following are overviews of each of Flare's output types—first the online output formats, then the
print-based formats, and finally the DITA code output.
Online Output Versus Print-based Output
There is a fine line between what is called "online output" and what is called "print-based" output.
The truth is that topics in virtually any of Flare's online output types can be sent to a printer (and
therefore considered "print-based"). Similarly, any of the print-based output types can be viewed electronically (and therefore considered "online"). The real distinction between online and print-based
outputs has to do with their primary purpose. Online outputs are usually intended to be viewed on
a screen, rather than on a printed page. The idea is to show only small pieces of content at a time
and allow users to jump around to other topics or elements of the output. On the other hand, printbased output follows a more traditional format that you would find in an actual book or manual—
with the pieces of the output following one after the other on pages until the end of the book (e.g.,
title page, table of contents, preface, chapters, index, appendixes—with page numbers, as well as
header or footer content, shown along the way).
About DotNet Help Output
DotNet Help is a Help output format developed by MadCap Software for Windows desktop applications. It was designed to include the best attributes of HTML Help and WebHelp, while filling the
holes left behind by those formats. DotNet Help is designed specifically to support Visual Studio
developers. It includes a freely redistributable viewer (MadCap Help Viewer), as well as components
for the Visual Studio developer. These components can be dropped into your Flare project to facilitate context-sensitive Help, embedded Help, and features such as automated search string communication between the application and the DotNet Help documentation. The DotNet Help output consists of a collection of files that you will distribute to users with the
freely downloadable MadCap Help Viewer. The main entry file has an .mchelp extension.
DotNet Help is a good choice if:
n
You need a format that supports .NET applications.
n
You want to produce a customizable interface that is much more modern looking than the
aging HTML Help. It will blend easily into a modern Vista environment.
n
You want users to be able to select between multiple languages for the interface when viewing
your output. This is possible because the freely distributable MadCap Help Viewer lets users
select English, French, German, or Japanese for the interface.
n
You do not want users to be burdened by the security warnings and limitations that are often
encountered with HTML Help and WebHelp.
n
You need to include features that are not available with HTML Help.
n
You want to create embedded context-sensitive Help in a .NET application. This includes the
ability to produce Dynamic Help.
n
You want to include search functionality that supports wildcard searches.
Flare's online Help uses DotNet Help.
- 419 -
MADCAP FLARE
About DotNet Help Output
HTML Help is an HTML-based Help format that runs on Windows 32-bit platforms and requires
Internet Explorer on the end users' systems. You can use HTML Help to create Help for Windows
desktop applications. The HTML Help output consists of a single CHM file that you will distribute to users.
HTML Help is a good choice if:
n
You are writing Help for a 32-bit Windows application.
n
Your users will have Internet Explorer on their system.
n
Your users don't have a network connection.
n
You want to create output that has just one file.
Note: Your users need Internet Explorer (4.0 or later) installed and a 32-bit Windows operating
system (Windows 95 or later).
About WebHelp Output
WebHelp is a Web-based Help format that can run on almost any browser or platform. You can use
WebHelp to create online documentation for the Internet or an intranet, as well as for desktop
applications. The WebHelp output consists of a collection of files that you will distribute to users. The output will
be displayed in the user's Internet browser window. The main entry file has an .htm extension.
WebHelp is a good choice if:
n
You are writing online documentation for distribution on the Internet or an intranet.
n
You want to be able to produce an output interface in various languages. This is possible
through the use of language skins.
n
You want the flexibility to include the online documentation in a desktop application.
n
Your users have different Internet browsers on their systems.
n
Your users are working on different platforms.
About WebHelp AIR Output
WebHelp AIR is a Web-based Help format that is identical to the regular WebHelp output in most
ways. However, WebHelp AIR uses direct integration with Adobe AIR, which is designed to bring
Web-related content to a desktop environment by taking Web files and incorporating them into a single file to be opened locally, rather than from a server. The WebHelp AIR output that you generate consists of a single file with an .air extension, which you
distribute to users. When users access this file, they are taken through an installation process, and
as a result an executable file with an .exe extension is created on their local drive and saved in their
C:\Program Files directory. In other words, the output becomes its own application. The output will
be displayed in the application window that is part of the AIR installation.
- 420 -
WebHelp AIR is a good choice if:
n
You want all of the features and benefits available with WebHelp.
n
You want to be able to distribute a single file, as opposed to multiple output files.
n
You want users to store and open the output locally, rather than from a server, such as a website.
n
You want to create output that has just one file.
n
You want users to be able to install the file not only in Windows, but in a Macintosh and
Linux environment as well.
In order for you and your end users to take advantage of this output, both you and they must perform additional installations.
n
Java Runtime Environment installation (you) As the individual compiling the output,
you need to install the Java Runtime Environment (JRE) before generating output.
You can download the JRE from http://java.sun.com/javase/downloads/index.jsp.
n
Adobe AIR installation (you and end users) Anyone who wants to view the generated
WebHelp AIR output needs to install Adobe AIR first. This means that both you and your end
users must run this installation.
You can download Adobe AIR from http://get.adobe.com/air/.
About WebHelp Mobile Output
WebHelp Mobile is an output type that lets you deploy Web- based, XHTML output to mobile
devices. WebHelp Mobile maintains an easy and intuitive interface that fits on a very small screen.
The Home page in WebHelp Mobile output contains navigation links to access the various panes
that you can include: TOC, Index, Glossary, Search, Favorites, Browse Sequences.
The WebHelp Mobile output consists of a collection of files that you distribute to users by placing
them on a Web server. End users then use their mobile device to open those files, just as they would
open any website. The output will be displayed in the user's mobile browser. The main entry file has
an .htm extension.
WebHelp Mobile is a good choice if:
n
Your end users are on the move and need to be able to access your documentation on their
mobile devices.
n
You want to be able to produce an output interface in various languages. This is possible
through the use of language skins.
n
Your users are working on different mobile platforms. Some of the major platforms supported
are iPhone, Windows Mobile, and Blackberry.
Note: Some older mobile browsers do not support certain features (e.g., DHTML, search),
whereas newer mobile browsers do support them. Other features, such as "mouse over," are not
supported in either older or newer mobile browsers.
- 421 -
MADCAP FLARE
About WebHelp Plus Output
WebHelp Plus is a Web-based Help format that is identical to the regular WebHelp output in most
ways. However, WebHelp Plus is designed to work on a Web server running Windows XP, Windows
Server 2003, Windows Server 2008, Windows 7, or Windows Vista. It also uses Microsoft Internet
Information Services (IIS) and ASP.NET. To provide faster search, WebHelp Plus uses Microsoft
Indexing Service (for Windows XP and Windows Server 2003) or Windows Search (for Windows
Server 2008). The benefit of publishing WebHelp Plus output is that you and your users can take
advantage of some advanced features, including searching of non-XHTML content, faster server-side
search, and automatic runtime merging.
The WebHelp Plus output consists of a collection of files that you will distribute to users by publishing output to a Microsoft IIS Web server. The output will be displayed in the user's Internet
browser window. The main entry file has an .htm extension.
WebHelp Plus is a good choice if:
n
You want all of the features and benefits available with WebHelp.
n
You want users to experience faster searches in your output.
n
You want non-XHTML files (e.g., PDFs, Excel spreadsheets) to be included in searches that
users perform in your output (even if those non-XHTML files are not part of your project).
n
You want to automatically merge the output for multiple Flare projects so that they appear as
one large Help system to end users.
n
You publish your output to a machine running Windows XP, Windows Server 2003, Windows
Server 2008, Windows 7, or Windows Vista.
- 422 -
Output Type Comparison Table—Online Output Types
Following are the various online output types available, with the distinguishing features of each.
DotNet
Help
HTML
Help
WebHelp
WebHelp
AIR
WebHelp WebHelp
Mobile
Plus
Main entry file
extension
.mchelp
.chm
.htm
.air
.htm
.htm
Output window
MadCap
Help
Viewer
Microsoft
HTML
Help
Viewer
Browser
window
Application
window
Mobile
Web
browser
Browser
window
Platform
Desktop
Desktop
Web
Desktop
Mobile
Web
Web
MadCap
DotNet
Help
Viewer
Internet
Explorer
General
.NET integration
Single output file
Special requirements
Java Runtime Environment
(JRE)
Adobe AIR
IIS
ASP.NET
MS Indexing Service
Accessibility (e.g., Section 508, WCAG)
Accessibility supported
Context-sensitive Help (CSH)
CSH supported
Embedded CSH supported
Feedback statistics and reporting features
Feedback supported
Search results
Generated content
Breadcrumbs
Browse sequences
- 423 -
MADCAP FLARE
DotNet
Help
Concept links
Glossaries
Indexes
Keyword links
Mini-TOCs
Related topics links
Relationship links
Scripts
Shortcut controls
TOCs
Topic toolbars
Language support
Content—display in
any left to right language
Output interface—
display in any left to
right language
Output interface—
display English,
French, Japanese,
or German
Master pages
Master pages supported
Merging output
Merge output supported
- 424 -
Possible
with Help
Viewer
(end user
selects language)
HTML
Help
WebHelp
WebHelp
AIR
WebHelp WebHelp
Mobile
Plus
DotNet
Help
HTML
Help
WebHelp
WebHelp
AIR
WebHelp WebHelp
Mobile
Plus
Merge output at runtime
Multimedia
Audio
If mobile
browser
supports it
Movies
If mobile
browser
supports it
Search
Search supported
Include/exclude topics in search
Only supported in
newer
mobile
browsers
Search filter sets
Search non-XHTML
files
Stop words
Only supported in
newer
mobile
browsers
Uses indexing service
Synonyms
Only supported in
newer
mobile
browsers
- 425 -
MADCAP FLARE
DotNet
Help
HTML
Help
Only some
styles
(e.g., Feedback, toolbar) are
supported.
Only some
styles
(e.g., Feedback, toolbar) are
supported.
Wildcard searches
supported
Skin settings
About box
Accordion titles
Browser settings
Caption for output
window
Elements (e.g., tabs,
accordions)—specify
default element
Elements (e.g., tabs,
accordions)—specify
which to include
Feedback user profile
Index—binary
Index—include bookmarks in index
entries
Language skins
Navigation links in
standalone topics
Navigation pane settings
Preview skin for output type
Size/position—specify
Styles
- 426 -
WebHelp
WebHelp
AIR
WebHelp WebHelp
Mobile
Plus
DotNet
Help
HTML
Help
WebHelp
WebHelp
AIR
WebHelp WebHelp
Mobile
Plus
TOC—binary
TOC—synchronize
with topics
Topic toolbar custom settings
Limited
settings
Target settings
Accessibility warnings
Characters and
spaces—replace with
underscores
Content folder—
omit from output
DOCTYPE declaration
Standard
mobile
DOCTYPE
always
used
File extensions—custom
Images—pre-compile resized
Images—Web-safe
Language—select for
output interface
Mark of the Web
Master page
Skins—generate all
Startup topic
Style sheet medium
- 427 -
MADCAP FLARE
About PDF Output
Short for "Portable Document Format," PDF is an open file format created by Adobe. PDF files represent two-dimensional documents in a device-independent and resolution-independent fixed-layout
document format. You can generate PDF output from your project directly, or you can generate a
PDF while simultaneously building FrameMaker or Word output. PDF is a good choice if:
n
You want to use a format with which most end users are familiar.
n
You want users to be able to view the book online, as well as print it.
PDF output consists of a file with a .pdf extension that you can print or distribute to users.
You can also set PDF options in the Target Editor. These options let you specify the way that
images, document properties, the initial view, and security are handled in the output.
About XHTML Output
XHTML is a browser-based output type that consolidates project content in an XML file. It can be
viewed online or printed.
XHTML is a good choice if you need an "intermediary" format for your large, custom, enterprise level
proprietary systems. You can easily transform Flare-authored content into your own system. By creating the single file output, you can feed it into your own parser/transform and convert all of the
Flare content to your internal formats. This is part of the flexibility that allows Flare to be integrated
into just about any tool chain or work flow. If you do not have a situation like that, you may find
one of the other formats to be a more suitable option for you.
XHTML consists of a collection of XHTML files that you can print or distribute to users. This
includes:
n
A file with an .htm extension. This is the XHTML file that contains the consolidated topic
content from your project.
n
A file with an .mcbook extension. This file is used to display the chapters in the MadCap
Book Viewer.
n
A Resources folder with various ancillary files, such as style sheets and images.
If you want to make XHTML output accessible for others, you need to include all of the files in the
output mentioned in this list. Otherwise, when they view the output, certain elements (e.g., images)
might be missing from the pages.
- 428 -
About XPS Output
Microsoft's XML Paper Specification (XPS) is a document format with a markup language that is a
subset of XAML for Windows Presentation Foundation. XPS is an alternative to Adobe's Portable
Document Format (PDF). You can generate XPS output from your project directly. Make sure you
have the latest version of Microsoft .NET Framework installed on your computer. This is a free download from microsoft.com. Alternatively, you can generate XPS output while simultaneously building
Word 2007 output (by installing a free add-in download from Microsoft).
XPS is a good choice if:
n
You want to create output in a smaller file size than you would get from Adobe PDF.
n
You want users to be able to view the book online, as well as print it.
n
You want to take advantage of the benefits provided by XPS, such as better print quality, easy
file sharing, and enhanced security.
XPS output consists of a collection of XPS files that you can print or distribute to users. This
includes:
n
A file with an .xps extension. This is the file that contains the consolidated topic content
from your project. This is the main file and the only one that is essential. This is the file that
you would provide to a printer or distribute to end users.
n
If you want users to download an XPS document from a server, you need to enable the server to do
this by registering the MIME types and file extensions. For steps see the online Help.
About Microsoft Word Output
Word is an output type where the generated project is exported to Microsoft Word in one of the following formats: XML (default), DOC, DOCX, XPS, PDF. However, you can also create PDF or XPS
output directly, without going through Word.
Note: Unless you specify otherwise, the Word target will create files with an .xml extension
only. If you want to use one of the other formats see the online Help.
Note: Flare supports Microsoft Word 2003 and newer versions.
Note: To create output in DOCX or XPS format, you need to have Microsoft Word 2007
installed. Also, Word 2007 allows you to create PDF files from Word without needing to have
the Adobe Distiller installed.
- 429 -
MADCAP FLARE
About Adobe FrameMaker Output
FrameMaker is an output type where the generated project is exported to Adobe FrameMaker in one
of the following formats: BOOK, FM, PDF. However, you can also create PDF output directly, without going through FrameMaker.
Note: Flare supports FrameMaker 7.0 and newer versions.
Output Type Comparison Table—Print-based Output Types
Following are the various print-based output types available, with the distinguishing features of
each.
XPS
MS
Word
PDF
XHTML
FrameMaker
Primary benefits
Familiar to
many users
Good for large, custom, enterprise
level systems
Main entry
file extension
.pdf
.htm
.xps
.xml
(default)
.fm or .book
Output files
necessary to
distribute
.pdf file only
All files generated
.xps file
only
All files
generated
All files generated
Program used
to view output
Browser window or Adobe
PDF Reader
Browser window
Browser
window
Microsoft
Word
Adobe FrameMaker
Smaller
Work with Work with outfile size
output in put in Framethan PDF
Word
Maker
Better
print quality
Easy file
sharing
Enhanced
security
About DITA Output
Darwin Information Typing Architecture (DITA) file content is supported in Flare. DITA is an XMLbased markup language with its own schema for authoring, producing, and delivering technical
information. It is a standard of the Organization for the Advancement of Structured Information
Standards (OASIS), and it consists of a set of design principles for creating "information-typed" modules at a topic level and for using that content in various delivery modes.
DITA allows companies (especially larger ones) to maintain better consistency throughout its documentation by establishing structural rules and standards for all of its authors to follow. The idea is
- 430 -
that writers will spend more of their time authoring content, rather than worrying about the presentation of that information.
In Flare you can generate output that produces DITA files. When you build this type of output, a
DITA map file is generated, with multiple DITA files in it. The XHTML tags are converted to DITA
elements. In other words, although it is considered an "output" from the standpoint of the Flare
process, the end result is actually a collection of "source" files, which you can later use in another
tool (or import back into Flare) to produce the final output.
- 431 -
MADCAP FLARE
Changing The Output Type For A Target
Each target in your project is based on one of the output types that is available in Flare (DotNet
Help, HTML Help, WebHelp, WebHelp Plus, WebHelp AIR, WebHelp Mobile, Adobe PDF, XHTML,
Microsoft XPS, Microsoft Word, Adobe FrameMaker, DITA). If you want a particular target to use a
different output type than is currently specified, use the following steps. You can also add an internal comment to describe the output.
How to change the output type for a target
1. From the Project Organizer, open the appropriate target.
2. Clcik the General tab.
3. From the Output Type field make a selection.
4. In the message that opens click Yes.
5. (Optional) In the Comment field, you can enter an internal comment that describes the output you are generating from the target.
to save your work.
Note: For help in determining which output type(s) you should use, see "Determining the Output Type" on page 419.
- 432 -
Adding Targets
In Flare you can add targets using any of the available formats, and you can make as many copies
of an existing target that you want. For example, your project might end up containing three targets
that are all based on the WebHelp output type (in addition to other targets).
How to add targets
1. Select Project>Add Target. The Add Target dialog opens.
n
n
3. In the File Name field, type a new name for the target.
4. From the Output Type field, select one of the available output formats. You can always
change the output type later in the Target Editor.
5. Click Add.
6. Click OK. The target is added to the Targets folder in the Project Organizer. The Target Editor
opens to the right.
- 433 -
MADCAP FLARE
How to make copies of targets
2. Double-click the Targets folder. The available targets are shown.
3. Click on the target that you want to copy.
4. In the Standard toolbar, click
.
5. In the Standard toolbar, click . A copy of the target is added to the Targets folder. The new
target is given the same name as the target you copied, with the words "Copy of" before it.
- 434 -
Renaming Targets
It is usually helpful to rename the targets that you use to reflect the nature of your project (especially if you are using multiple targets with the same output type).
E X AMPLE
If y ou are u sing Dot Net Help t o p rod u ce a Help sy st em for a soft ware ap p licat ion
called Doohickey Pro, y ou might want t o rename t he t arget "Doohickey Pro. " If y ou
are creat ing a beginner's v ersion and an ad v anced v ersion of y ou r Help sy st em , y ou
might want t o name one t arget "Beginner Doohickey Pro" and t he ot her t arget
"Ad v anced Doohickey Pro. " That wou ld be mu ch easier t han t ry ing t o d ist ingu ish
bet ween t arget s called "My Dot Net Help " and "C op y of My Dot Net Help . "
How to rename a target
2. Double-click the Targets folder.
The available targets are shown.
3. Click on the target that you want to rename.
4. Press F2.
The name in the target is highlighted.
5. Type a new name for the target and press Enter on your keyboard.
The target is renamed.
- 435 -
MADCAP FLARE
Setting A Primary Target
You can have as many targets in your project that you want, and any of your targets can be built
(generated) whenever you like. However, chances are that you will have one target that you work
with more than the others. You can set it as your primary target.
When you first create a project, the Start New Project Wizard asks you to specify a primary target.
The steps below show you how to change which target is the primary one.
How to set a primary target
3. Right-click on the target that you want to make the primary target. In the context menu,
select Make Primary.
The new primary target displays in bold font with "(Primary)" added after it.
- 436 -
A condition tag is a marker that you can apply to different areas of your content so that some sections show up in some of your outputs but not in others. It is just one of the many single-sourcing
features that you can use in Flare.
E X AMPLE
Let 's say y ou need t o creat e t wo PDFs from y ou r p roject — one for beginning u sers
and anot her for ad v anced u sers. Rat her t han creat ing t wo sep arat e p roject s, y ou can
p ut all of t he cont ent int o a single p roject . Then y ou can creat e one cond it ion t ag
called "Beginner Manu al" and anot her cond it ion t ag called "Ad v anced Manu al. "
Aft er t hat , y ou can ap p ly t he "Beginner Manu al" cond it ion t ag t o t he cont ent t hat
belongs only in t he manu al for beginners, and y ou can ap p ly t he "Ad v anced Manual"
cond it ion t ag t o t he cont ent t hat belongs only in t he manu al for ad v anced u sers.
Finally , y ou associat e one t arget in y ou r p roject wit h t he beginner manu al (and it s
cond it ion t ag) and anot her t arget wit h t he ad v anced manu al (and it s cond it ion
t ag).
Condition Tag Integration With Mimic And Capture
If you are also using MadCap Mimic or Capture (or both), you can use condition tags that exist in
your Flare project. This is similar to the variable integration that exists with these products.
E X AMPLE
Let 's say t hat y ou hav e creat ed t wo cond it ion t ags in a Flare p roject in ord er t o
send p art s of y ou r cont ent t o d ifferent ou t p u t s— one cond it ion t ag called "Beginner"
and t he ot her called "Ad v anced . "
Now sup p ose y ou insert a p ict u re int o t hat Flare p roject and t hen op en t he image in
C ap t ure in ord er t o ed it it . Becau se y ou insert ed t he image int o t he p roject , a connect ion alread y exist s bet ween t he Flare p roject and t he image while y ou work on it
in C ap t ure.
This means t hat if y ou at t emp t t o ap p ly cond it ion t ags t o t he image while it is in
C ap t ure, y ou will hav e access t o t he "Beginner" and "Ad v anced " cond it ion t ags t hat
y ou creat ed in t he Flare p roject .
- 437 -
MADCAP FLARE
Steps For Using Condition Tags
Following are the basic steps involved with condition tags.
1. Add condition tag set A condition tag set is used to hold condition tags you create for your
project. Flare's factory templates provide you with an initial condition tag set, which contains
two condition tags (PrintOnly and ScreenOnly) to help get you started. You can create as
many additional condition tags as you want for that condition tag set. However, if for some
reason you want more condition tag sets to hold even more condition tags, you can easily add
them. For more information see the online Help.
2. Create condition tags Within a condition tag set, you can create as many condition tags
as you need. See "Creating Condition Tags" on the following page.
3. Apply condition tags to content After you create condition tags, you can apply them to
the appropriate content in your project. You can apply condition tags to many different elements in your project, including files that make up the project (e.g., topics, snippets, images,
style sheets, TOCs, outputs, targets), full paragraphs, text within paragraphs, table rows and
columns, TOC entries, and index keyword markers. See "Applying Condition Tags to Content"
on page 441.
4. Associate condition tags with targets After creating and applying condition tags, you
need to tell Flare what your target should do with the condition tags that you have created
and applied. Should content with a particular condition tag be included in or excluded from
that target? See "Associating Condition Tags with Targets" on page 447.
Note: Condition tags are not supported if you are generating a target using the DITA output type, in the sense that you cannot include or exclude condition tags for that DITA output. Therefore, when you open a DITA target, the options in the Conditional Text tab are
disabled. However, DITA-specific condition tag attributes are preserved in Flare when
you import from DITA; the DITA attributes are converted to condition tag sets in Flare. In
fact, you can create custom condition tag sets in Flare that can be useful when you generate DITA output from Flare. You simply need to make sure that the condition tag sets
follow the established DITA naming conventions for those attributes: condition tag sets
can be named "audience," "product," "platform," "props," and "otherprops." When you generate the output, the condition tag sets are converted to the appropriate DITA attributes.
- 438 -
Within a condition tag set, you can create as many condition tags as you need.
How to create a condition tag
2. Double-click the Conditional Text folder. The folder opens, showing an initial condition tag
set provided by Flare, as well as any condition tag sets that you have added to the project. A
condition tag set can hold multiple condition tags. (If there is no condition tag set, add one
by selecting Project>Add Condition Tag Set.)
3. Double-click a condition tag set to open it.
The Condition Tag Set Editor opens. If it is a new condition tag set, two condition tags may
already be provided for you—one called "PrintOnly" and another called "ScreenOnly." Each
condition tag is associated with a color, making it easy to identify conditionalized content in
the Flare interface. By default, the PrintOnly tag is associated with the color red, and the
ScreenOnly tag is associated with the color blue.
4. At this point, you can do a number of things, including the following:
n
Add a new tag You can add as many tags as you want, depending on your needs.
a. In the local toolbar of the Condition Tag Set Editor, click the New item button
. A new row is added.
b. Press F2 on your keyboard.
c. Replace the temporary tag name with a new one.
n
Rename an existing tag Maybe you want to use the existing tags, but you want
them to have different names to reflect your purposes. For example, you might rename
the "PrintOnly" tag to "Beginner," and you might rename the "ScreenOnly" tag to
"Advanced."
a. Click the tag and press F2 on your keyboard. The tag name is highlighted.
b. Type a new tag name.
c. Press Enter on your keyboard.
Warning: If you rename a condition tag that has already been applied to content
in your project, you must update those areas as well. Otherwise, you will have
undefined condition tags that will not work in the output. One of the best ways to
do this is to rename the condition tag and then perform a "find and replace" in
the source code throughout your project. For example, let's say you have a condition tag set called "MyTagSet" and within that file you have a condition tag
named "Beginner." You change the name of the condition tag to "Newbie." In that
case, open any content file (e.g., a topic) and select Edit>Find and
Replace>Find and Replace. In the Find and Replace window pane, click in
the Find what field and enter MyTagSet.Beginner. Click in the Replace
- 439 -
MADCAP FLARE
with field and enter MyTagSet .Newbie. From the Find in drop-down field,
select (whole project). Click the check box Find in source code. Then click
Start. You can replace each occurrence manually or you can replace all instances
of that text.
n
Change the color of a tag You can associate any color you want with a condition
tag. The color is for your use only; end users will not see it in the output.
a. Click the Background drop-down arrow and select Pick Color . The Color
Picker dialog opens.
b. Select a new color.
c. Click OK.
n
Add comments to a tag You can add internal comments to a condition tag to indicate the specific purpose of the tag. Comments will not be displayed in the output.
a. Click in the Comment cell of the tag.
b. Press F2 on your keyboard.
c. Type comments for the tag.
d. Press Enter on your keyboard.
- 440 -
to save your work.
Applying Condition Tags To Content
After you create condition tags, you can apply them to the appropriate content in your project.
E X AMPLE
Let 's say y ou hav e one cond it ion t ag for a beginner's v ersion of a manu al called
"Beginner Doohickey Pro" and anot her cond it ion t ag for an ad v anced v ersion of t he
manual called "Ad v anced Doohickey Pro. " If y ou hav e a sent ence in a t op ic t hat p ert ains only t o t he beginner's v ersion, y ou wou ld select t hat sent ence and ap p ly t he
"Beginner Doohickey Pro" t ag t o it . You might hav e anot her sent ence in t he same
t op ic t hat p ert ains only t o t he ad v anced v ersion of y ou r manu al, so y ou would
ap p ly t he "Ad v anced Doohickey Pro" t ag t o it .
You can apply condition tags to many different elements in your project, including files that make
up the project (e.g., topic, image, style sheet, glossary, skin, target files), full paragraphs, text
within paragraphs, table rows and columns, table of contents (TOC) entries, and index keyword
markers. For full details about applying condition tags to each of these elements, see the online
Help. In this manual, we will describe the steps for applying condition tags to selected text within a
paragraph, to an entire block of content in a topic, and to a project or content file.
- 441 -
MADCAP FLARE
How to apply condition tags to selected text within a paragraph
2. Highlight the text to which you want to apply the condition tag.
3. Select Format>Conditions. The Condition Tags dialog opens, with the first condition tag
set selected and the associated condition tags shown on the right.
4. If you want to see condition tags for a different condition tag set, select it.
5. For each condition tag that you want to apply to the text, click the check box next to the tag.
A check mark appears in the box.
6. Click OK.
7. There are a couple of ways to tell whether a selection of text has one or more condition tags
applied to it. In the bottom local toolbar of the XML Editor, click either of the following two
toggle buttons to turn the tag indicators on and off.
Click this button at the bottom of the XML Editor to show or hide shading of
the text itself. For example, if your condition tag has blue associated with it and
you click this button to show the indicator, the text becomes shaded with a
lighter version of blue. If more than one condition tag is applied to the text, the
shading appears in a pattern that shows all of the applied condition tag colors.
Click this button at the bottom of the XML Editor to show or hide the span bar
above the topic. When the cursor is on the text containing the applied tag, the
span bar is shaded with a lighter version of the tag color. This is a good feature
to use if you find the shading of the actual text distracting.
- 442 -
to save your work.
How to apply condition tags to an entire block of content in a topic
Topics usually contain several blocks of XML content. For example, there are HTML blocks, body
blocks, paragraph blocks, table blocks, and heading blocks. You can apply a condition tag to any
block of content in your topics.
2. Make sure the tag block bars are visible on the left side of the XML Editor. If they are not,
click
at the bottom of the local toolbar to show them.
3. Right-click on the tag bar for the block of content to which you want to apply the condition
tag.
- 443 -
MADCAP FLARE
4. In the context menu, select Conditions. The Condition Tags dialog opens, with the first condition tag set selected and the associated condition tags shown on the right.
6. For each condition tag that you want to apply to the block of content, click the check box next
to the tag. A check mark appears in the box.
7. Click OK.
8. There are two ways to tell whether a block of content has condition tags applied to it. In the
bottom local toolbar of the XML Editor, click one of the following toggle buttons to turn the
tag indicators on and off:
Click this button at the bottom of the XML Editor to show or hide shading of
the block of content itself. For example, if your condition tag has blue associated
with it and you click this button to show the indicator, the block of content
becomes shaded with a lighter version of blue. If more than one condition tag is
applied to the block of content, the shading appears in a pattern that shows all
of the applied condition tag colors.
Click this button at the bottom of the XML Editor to show or hide the tag block
bar to the left of the topic. When the cursor is on the block of content containing
the applied tag, the tag bar is shaded with a lighter version of the tag color. This
is a good feature to use if you find the shading of the actual content distracting.
- 444 -
to save your work.
How to apply condition tags to project or content files in a project
You can include or exclude entire files from a target. This includes any file contained in the Project
Organizer (such as glossary or target files) or the Content Explorer (such as topic, image, style sheet,
snippet, and page layout files).
To apply condition tags to one file at a time:
1. Do one of the following, depending on whether you want to apply a condition tag to project
files or content files:
n
Make sure the Project Organizer is open.
OR
n
Make sure the Content Explorer is open.
2. Locate and click on the file to which you want to apply a condition tag. In the Project Organizer, files are stored in various folders. In the Content Explorer, topic files are located by
default at the top level (unless you place them in subfolders that you’ve created); other files
are located in subfolders within the Resources folder. For example, snippet files are located in
a subfolder called "Snippets."
3. In the Standard toolbar, click
. The Properties dialog for the file opens.
4. Click the Conditional Text tab. The first condition tag set is selected and the associated condition tags are shown on the right.
6. For each condition tag that you want to apply to the file, click the check box next to the tag.
7. Click OK. The square next to the file name in the Project Organizer or Content Explorer now
takes on the color of the condition tag. If you applied more than one condition tag to the file,
each color is shown. (If you do not see squares, click
in the local toolbar.)
To apply condition tags to multiple files at once using the File List window pane (content files only):
1. Select View>File List or press CTRL+SHIFT+J on your keyboard.
2. (Optional) From the Filter list in the window pane, select the type of files to view.
3. Select the files to which you want to apply condition tags. You can hold the SHIFT key to
select a range of files, or you can hold the CTRL key to select individual files.
4. In the local toolbar, click
5. Click the Conditional Text tab. The first condition tag set is selected and the associated condition tags are shown on the right.
7. For each condition tag that you want to apply to the files, click the check box next to the tag.
- 445 -
MADCAP FLARE
8. Click OK. The squares next to the file names in the File List window pane now take on the
color of the condition tag. If you applied more than one condition tag to the file, each color is
shown.
To apply condition tags to multiple project or content files at once using the Split
View feature:
1. Do one of the following, depending on whether you want to apply a condition tag to project
files or content files:
n
Make sure the Project Organizer is open.
OR
n
Make sure the Content Explorer is open.
2. In the Project Organizer or Content Explorer, click the Show Files button
.
The Project Organizer or Content Explorer splits into two halves (left and right).
3. On the left side of the split Project Organizer or Content Explorer, select the folder containing
the files to which you want to apply condition tags.
4. On the right side of the split Project Organizer or Content Explorer, select the files. You can
5. In the toolbar click
.
The Properties dialog opens.
6. Click the Conditional Text tab.
The first condition tag set is selected and the associated condition tags are shown on the
right.
8. For each condition tag that you want to apply to the files, click the check box next to the tag.
9. Click OK.
The square next to the file name in the Project Organizer or Content Explorer now takes on
the color of the condition tag. If you applied more than one condition tag to the file, each
color is shown in the square. (If you do not see squares, click
in the local toolbar.)
10. To hide the split view, click the Show Files button
- 446 -
to save your work.
again.
Associating Condition Tags With Targets
After creating and applying condition tags, you need to tell Flare what your target should do with
the condition tags that you have created and applied. Should content with a particular condition
tag be included in or excluded from that target?
How to associate a condition tag with a target
2. Double-click the Targets folder. The folder opens, showing the targets in your project.
3. Double-click the target that you want to associate with one or more condition tags. The Target Editor opens to the right.
4. Click the Conditional Text tab.
5. In the Condition Tag Sets area, you can choose to view tags for all condition tag sets or
you can select a specific set. The tags associated with the selected set are shown to the right,
with their associated colors. An Include and Exclude check box appears next to each condition tag.
6. By default, all tags will be included in the target unless you specify otherwise. If you want to
exclude a condition tag from the output for this target, click the Exclude check box next to
it. If you want to make sure a condition tag is included in the output for this target, click the
Include check box next to it.
Why is there an Include check box if all tags are included by default? The Include check box is
necessary in case you have two or more tags associated with the same content and there is a
conflict.
E X AMPLE
Sup p ose y ou hav e t wo cond it ion t ags in y ou r p roject — one called "Beginner"
and anot her called "Ad v anced . " Let 's say t hat y ou hav e a t op ic cont aining
t hree p aragrap hs. You ap p ly t he "Ad v anced " t ag t o t he first t wo p aragrap hs,
and y ou ap p ly t he "Beginner" t ag t o t he last t wo p aragrap hs.
You hav e creat ed a t arget called "Ad v anced Set Up . " For t his t arget , y ou
obv iou sly want t o inclu d e all cont ent associat ed wit h t he "Ad v anced " t ag, but
y ou want t o exclu d e cont ent associat ed wit h t he "Beginner" t ag.
By d efau lt , Flare will inclu d e cont ent associat ed wit h bot h t ags, u nless y ou
t ell it not t o. So y ou t ell Flare t o exclu d e t he cont ent associat ed wit h t he
"Beginner" t ag. The p roblem is t he mid d le p aragrap h from t he t op ic ment ioned
abov e. It is associat ed wit h bot h t ags. You hav e t old Flare t o exclu d e cont ent
associat ed wit h t he "Beginner" t ag, and it will d o so, ov errid ing t he d efault .
But y ou want t o make su re t hat p aragrap h is inclu d ed in t he "Ad v anced Set
Up " ou t p u t . That is why y ou need t o make su re y ou select t he Inclu d e check
box next t o t he "Ad v anced " t ag.
to save your work.
- 447 -
MADCAP FLARE
Using the Target Editor, you can edit properties for any of your targets.
How to edit a target
1. From the Targets folder in the Project Organizer, open the target that you want to edit.
2. You can use the tabs in the Target Editor to perform various tasks, depending on the output
type associated with the target (i.e., some tasks can be performed only in certain targets).
Tasks include the following.
- 448 -
n
Accessibility warnings For WebHelp and PDF outputs you can use the Target
Editor to to indicate whether you want to receive compiler warnings when your output
fails to include information that makes it accessible. For more information see the
online Help.
n
Browse sequence (associate) If you have created only one browse sequence for
your project, you do not need to associate it with a target. It will display automatically
after you build the target. However, if you have added more browse sequences, you
need to specify which one will serve as the "master browse sequence." This is the
browse sequence that will be displayed in the output. The additional browse sequences
will also be displayed if you have linked to them from the master browse sequence. You
can use the Target Editor to associate a master TOC with a target. See "Associating a
Browse Sequence with a Target" on page 93.
n
Build (generate) output You can use the Target Editor to build a target in your
project that is not designated as your primary target. See "Building a Single Target" on
page 460.
n
Condition tags (associate) After you create and apply condition tags to content,
you need to tell Flare what your target should do with the condition tags that you have
created and applied. Should content with a particular condition tag be included in or
excluded from that target? See "Associating Condition Tags with Targets" on the previous page.
n
Context-sensitive Help - alias file (associate) An alias file is used to populate a
header file with the information necessary for producing context-sensitive Help (CSH).
If you have added more than one alias file for your project, you need to associate the
appropriate alias file with the target that you plan to build. If you do not specify an
alias file in a target, Flare uses the first alias file listed in the Project Organizer. See
"Associating an Alias File with a Target" on page 122.
n
DOCTYPE declaration (add)You can add the DOCTYPE declaration to topic files
when you generate online output. This allows browsers to render the topics in strict
mode. If you do not select this option, generated topics will not have this declaration
and will be rendered by browsers in quirks mode.Quirks mode and strict mode have to
do with the evolution of web browsers and the rules they use to interpret styles in cascading style sheets (CSS). Quirks mode follows the old rules, and strict mode follows
the new rules. If you are not concerned about which mode is used for your online
output, you do not need to add the DOCTYPE declaration to topics. However, if you
want to ensure that your output is interpreted and displayed using the newer strict
mode, you should use this option.
Why use the DOCTYPE declaration? You might find the need to use the
DOCTYPE declaration feature if you have text boxes, images, tables, or other objects
that have float, margin, or padding settings applied to them. With settings such as
this, you might notice slight alignment issues when generating online output. For
example, margin or padding settings might be pushing aligned text a bit further than
you want. To fix this, add the DOCTYPE declaration to the target.
Note: This option is not necessary for WebHelp Mobile output because that output
type always includes the standard mobile DOCTYPE.
n
Feedback (enable) If you purchase the MadCap Feedback Service in order to track
user activity on your online output, a separate license is required for each target that
you want to associate with Feedback. After obtaining the necessary Feedback license(s),
you need to enable the Feedback functionality in Flare. This is done on the Feedback
tab in the appropriate targets. For more information see the online Help.
n
Glossaries (associate) If you are including one or more glossaries in your output,
you need to associate them with the target. After you build the target, the glossary will
be incorporated into the output and terms will be converted to links in individual topics (if you have selected one of the term conversion options in the Target Editor). See
"Associating Glossaries with Targets" on page 145.
n
HTML Help - jump buttons (specify) You can specify the destination (URL) for
the Jump1, Jump2, and Home buttons that can be included in HTML Help output.
You can also set these destinations in the Skin Editor (HTML Help Setup tab) and associate that skin with the target (on the General tab of the Target Editor). The reason this
option is available in both the Skin Editor and Target Editor is this: If you want multiple targets to use one skin, with each target using the same destinations for the jump
buttons, you should set the jump button URLs in the Skin Editor. If you want multiple
targets to use the same skin, but you want them to use different URLs for the jump buttons, set the URLs in the Target Editor. If URLs are set in both the Skin Editor and the
Target Editor, Flare uses the settings from the Skin Editor. For more information see
the online Help.
n
HTML Help - style sheet and image links (patch)If you generate HTML Help
output, some topics may not look as intended when they are printed from the CHM
file, due to style sheet-related problems. You can use this feature to "patch" those problems, ensuring the printed topics will look as intended. Why would you not use this
option? The only reason not to use this option is when you plan to rename the generated CHM file. If this option is enabled and you rename the CHM file, styles in the
output are broken. This happens because, when the option is enabled, the file name of
the CHM is hardcoded into the CHM itself.For more information see the online Help.
n
Importing - auto-sync (disable) Let's say you have imported Microsoft Word,
Adobe FrameMaker, or Flare files from another project, and when doing so, you
- 449 -
MADCAP FLARE
selected the "Easy Sync" option to automatically re-import the files when you generate
output. You can use this feature to override that Easy Sync setting for a specific target.
Therefore, if you want to re-import any of the files, you will need to do so manually.
You might decide to use this option, for example, if you are testing the generation of
output and do not want to wait the extra time for the files to be imported. After you finish your testing, you can deselect this option to return to the automatic imports of the
files. For more information see the online Help.
- 450 -
n
Index - search (excluding) If you insert index markers in your project, those
markers by default are included in searches that users perform in your output. If you
want to exclude index entries from searches, you can do so.For more information see
the online Help.
n
Language - WebHelp, WebHelp Plus, WebHelp AIR, or WebHelp Mobile
(select) If you are generating WebHelp, WebHelp Plus, WebHelp AIR, or WebHelp
Mobile output, you can select a specific language skin for displaying the user interface.
You can then edit the language skin as necessary, changing the way it looks as well as
adjusting text for buttons and labels. Normally, you would edit styles for a skin in the
Skin Editor. However if you want to display the output user interface in a particular
language, you can use the Language Skin Editor instead. For more information see the
online Help.
n
Mark of the Web (add) Mark of the Web (MOTW) is a comment added to the
HTML markup for a web page. When users open the web page from their local
machine, Internet Explorer references this comment to determine the security zone in
which it should run the page. This means you can deliver WebHelp or WebHelp Plus
output without your online Help initially being blocked on the user's machine with a
security message. For more information see the online Help.
n
Master page (associate) If you want a master page to be applied to all topics in the
output, you would associate that master page with the target that you are building.
This is useful, for example, if you want to create breadcrumbs, a mini-TOC, header content, or footer content for your online outputs (e.g., DotNet Help, HTML Help, WebHelp, WebHelp Plus, WebHelp AIR, WebHelp Mobile). See "Associating Master Pages
with Targets" on page 181.
n
Master pages (disable) Let's say you have used master pages in earlier versions of
Flare when creating Word or FrameMaker output, but now you decide to use the newer
page layouts instead. You can manually remove all links to master pages in your target
and table of contents. However, another alternative is to click this option instead. By
selecting this option, Flare will ignore all links to master pages when you generate the
Word or FrameMaker target. It will instead use links that you provide to any page layouts. For more information see the online Help.
n
Output file and folder (specify) When you build the output for a target in your
project, Flare sends the output files to the Output folder where your project is located.
It also uses a default name for the main entry file in the default output type. However,
you can specify a different location and main entry file name for a target's output files.
For Word and FrameMaker output, you can also specify a different output file type
than the default (e.g., add .pdf to the end of the file name, instead of .xml). For more
n
Output files - characters and spaces (replace with underscores) If you have
spaces or unusual characters in your file names or folders, you can covert these spaces
and characters to underscores in the output. This feature is primarily useful for individuals working in a UNIX environment. In addition to spaces, the characters that are converted to underscores include: ()&;,!'. For more information see the online Help.
n
Output files - custom extensions (specify) You can use specific file extensions for
topics for WebHelp output types. If you do not use this feature, the output topic files
will have an .htm extension. The most common alternative extensions are .html and
.aspx. To use this option, click the appropriate check box on the Advanced tab of the
Target Editor. Then type the file extension that you want to use in the text field. Do
not type the period, but rather the characters only. For more information see the online
Help.
n
Output files - lowercase names (convert) You can convert online output file
names and folders to all lowercase letters, even if the corresponding file names and folders in the project are not all lowercase. This option is useful, for example, if you are
working in a UNIX environment, which is case-sensitive. For more information see the
online Help.
n
Output folder - Content (omit) The Content subfolder in a project is normally used
to hold all of your content files. If you do not want this subfolder to be created when
you generate online output, you can omit it. When you use this option and build output, the content files will be placed at the root of the output folder instead, rather than
within the Content subfolder. For more information see the online Help.
n
Output type (change) Each target in your project is based on one of the output
types available in Flare (DotNet Help, HTML Help, WebHelp, WebHelp Plus, WebHelp
AIR, WebHelp Mobile, Adobe PDF, XHTML, Microsoft XPS, Microsoft Word, Adobe
FrameMaker, DITA). You can use the Target Editor to switch the output type for a particular target. You can also add an internal comment to describe the output. See
"Changing the Output Type for a Target" on page 432.
n
Page layout - master (associate) A page layout is an element that you can create
in your project in order to determine page specifications (e.g., size, margins) and to
apply certain content (e.g., headers, footers, page numbers) to many (or all) topics in
print-based output. Page layouts allow for easy configuration through the use of content frames, a snap-to grid, dragging and dropping, alignment features, and more.
Page layouts are similar to master pages, but are more flexible and easier to use. The
general rule of thumb is that page layouts are recommended for print-based output
(when possible), and master pages continue to be the best method for automatically
adding headers, footers, and breadcrumbs in multiple topics for online output. Another
difference between page layouts and master pages is that page layouts can be used for
any of the print-based outputs (Adobe PDF, XHTML, Microsoft XPS, Microsoft Word,
Adobe FrameMaker), whereas master pages can be used only for Microsoft Word and
FrameMaker when creating print-based output.
After you create a page layout and configure its frames and settings as necessary, you
need to associate the page layout with the appropriate content. In most cases, you will
probably want to associate different page layouts with various entries in your "outline
TOC" (so that different page layouts can be used for different parts or "chapters" in a
- 451 -
MADCAP FLARE
manual)—see Specifying Chapter Breaks and Page Layouts. Otherwise, you would associate a single "master" page layout with an entire target or project; in that case, the
same page layout will be applied to all topics in that target or project. Whenever you
associate a page layout with a TOC entry, you must first create a chapter break in order
to do so. In the Target Editor, you can associate a master page layout with a target.
n
PDF output (specify) If you are building either Microsoft Word or Adobe FrameMaker targets, you can send the output to Adobe's Portable Document Format (PDF)
as well. When you use this feature, Flare generates the native Word or FrameMaker documents, in addition to a PDF file. For more information see the online Help.
Please note, however, that you do not need Word or FrameMaker to generate PDF output; you can send output to PDF directly without first generating Word or FrameMaker.
- 452 -
n
PDF output - multiple documents (create) If you are generating PDF output
directly (rather than going through FrameMaker or Microsoft Word to produce it), you
can split the generated output into multiple documents, rather than using the default,
which results in only one document. To create multiple PDF documents, you must also
specify chapter breaks at the appropriate places in the TOC (not the TOC that displays
in the PDF output, but in the "outline TOC" used to determine the printed manual content and structure). This can be done on the Printed Output tab of the TOC Properties
dialog. By specifying chapter breaks, you are letting Flare know where you want to
split the output into new PDF documents. Then in the Advanced tab of the Target
Editor, select the "Generate multiple documents for native XPS/PDF output" option
n
PDF output - options (specify) If you are sending output directly to Adobe PDF,
you can access PDF options in the Target Editor. These options let you specify the way
that images, document properties, and the initial view are handled in the output. For
n
Performance (improve) You can improve the processing performance of your online
output in several ways. For more information see the online Help.
n
Pictures - resized scaled images (generate) When you use Flare's resizing features to scale images, you can specify whether you want Flare to pre-compile the
resized images. You can do this for the online outputs (DotNet Help, HTML Help, WebHelp, WebHelp Plus, WebHelp AIR, WebHelp Mobile), as well as for Microsoft Word
and Adobe FrameMaker output. What does this mean? It means that Flare will create
new copies of images wherever you have specified resizing, rather than relying on the
browser to render the new size from the original. This means better quality images, but
it also means more image files in the output. It is recommended that you leave the
default pre-compile setting as it is (enabled). However, if you want to disable it, you
can open the Target Editor, select the Advanced tab, and select Generate resized
copies of scaled images to remove the check mark. (For Adobe PDF, Microsoft XPS,
and XHTML output, the resized images will always be pre-compiled, whether this
option is enabled or not.) For more information see the online Help.
n
Pictures - web-safe images (generate) If you have used non–web-safe image formats (e.g., WMF, EMF, BMP, TIF, TIFF, XPS, EXPS) in your project, you can convert
those images to web-safe formats (e.g., GIF, JPEG, PNG) when you generate online output ( DotNet Help, HTML Help, WebHelp, WebHelp Plus, WebHelp AIR, WebHelp
Mobile). For print-based output types (Adobe PDF, XHTML, Microsoft XPS, Microsoft
Word, Adobe FrameMaker), the original image file formats will be used when you generate output. For more information see the online Help.
n
Printed output - online features (convert) Some online features in your project
are automatically handled in one way or another when you produce printed output.
However, there are some features (expanding text and popup effects) where you can
specify how you would like them to be treated in the printed output. For more information see the online Help.
n
Publish output After you build a target, you can publish the output to any destinations that you have created. See "Publishing Output to Destinations" on page 484.
n
Publishing destinations (associate) A publishing destination is used to tell Flare
where to send a copy of your output files. After you create a publishing destination,
you need to associate it with a target that you plan to build. You can associate the
same publishing destination with as many targets as you want. See "Associating Publishing Destinations with Targets" on page 483.
n
Redacted text (set) For each output (i.e., PDF or XPS document) that needs to
include redacted content, you can open the appropriate target. Then you can use the
Advanced tab to specify how the content marked as "redacted" should be treated in the
output. For more information see the online Help.
n
Relationship tables (associate) If you have created relationship tables in your
project, you need to tell Flare which tables to use for which targets. For more information see the online Help.
n
Search - filter set (associate) A filter can be included in the search feature to let
users narrow their search based on "concepts" that you have inserted into topics. Concepts are simply markers that you insert into topics that have some kind of relationship with each other. After you add a search filter set, you need to associate it with
the target that you want to build. For more information see the online Help.
n
Skin (associate) A skin is a file that contains information about the appearance of
the output window. After you add a skin to your project and edit the settings, you
need to associate it with a target. When you build the target, the output will be displayed in the skin. See "Associating Skins with Targets" on page 412.
n
Skins (generate all) An option on the Advanced tab of the Target Editor controls
whether every skin in the project or just the selected skin in the target (which is set on
the General tab) will be generated for the output. This option is enabled by default. The
reason to keep this option enabled is if you need the ability to make context-sensitive
Help (CSH) calls to different skins. In this case, each of those skins must be generated
so that they are available in the output for the CSH calls. If you are not using multiple
skins for CSH calls, you might want to disable this option. If you disable it, the size of
the entire output will be minimized because unnecessary skins will be excluded. For
n
Source control (get files automatically) If you have bound your project to a
source control program, you can use a setting in the Target Editor to automatically get
- 453 -
MADCAP FLARE
the latest version of all files prior to generating the target. You might use this option if
you are working with a team of authors and want to make sure that you include the
latest changes from other writers in the output (without having to manually get those
files). For more information see the online Help.
With this option:
n
You will not be prompted before the "get" is performed.
n
Flare will not get the latest copy of the files in the Targets folder, because that
would conflict with the generation of the output.
n
Conflicts with files will not cause local files to be overwritten. Therefore, if your
local files are writable or already checked out, those files will be kept, rather than
overwritten with the source control files.
Note: The "automatic get" feature is not supported if you are building output
using the command line, as opposed to the Flare interface.
n
Startup topic (specify) You can specify which topic in your project is the first one
that users see when they open the online output. If you have written a welcome or
introduction topic, you will likely want this to be the "startup" topic in your output.
n
Style sheet - master (associate) When you want to use styles in your content, the
style sheet needs to be made available for the content in question. In Flare, you can
associate style sheets with a single topic. However, you also have the option of using a
style sheet as a "master," applying it at either the project or target level, or both. In the
Target Editor, you can associate a master style sheet with a target. For more information see the online Help.
n
Style sheet - medium (associate) A medium is an alternative set of styles in a
style sheet that you use for different outputs. They are intended to be an exception to
the default style you want to use. You can use the Target Editor to associate a medium
with a particular target. A common use for a medium is to have one group of style settings for online formats (e.g., DotNet Help, HTML Help, WebHelp, WebHelp Plus, WebHelp AIR, WebHelp Mobile) and a different group of settings for print formats (Adobe
PDF, XHTML, Microsoft XPS, Microsoft Word, Adobe FrameMaker). Therefore, you
could use the default medium for the online formats and use a "print medium" for the
print-based targets. For more information see the online Help.
Note: When you create a print-based target (Adobe PDF, XHTML, Microsoft XPS,
Microsoft Word, Adobe FrameMaker), the "print" medium is automatically associated with that target (on the Advanced tab of the Target Editor). Of course, you
can always select a different medium if you want.
n
- 454 -
TOC - master (associate) In most situations, you will have one TOC that you use
for a particular output (target). In that case, you simply associate the appropriate TOC
with the target. If you have multiple TOCs that you want to include in the same
project or output target, the TOC that you associate with the project or target serves as
the "master" TOC. In your master TOC, you have the option of creating links to the
other TOC that you want to include in the output. If you do not select a TOC, Flare
will use the first one in the project (if there is more than one). If you have specified a
master TOC at the project level and another at a target level, the TOC at the target will
take precedence. See "Associating a Master Table of Contents with a Target" on page
345.
n
TOC - print-based output (heading levels, unlinked books, remove
images) There are a few settings in the Target Editor that let you control how a generated TOC is produced in print-based output.
l
Heading levels You can select an option to base the heading levels of your generated TOC on the structure of the outline TOC . When you generate print basedoutput (Adobe PDF, XHTML, Microsoft XPS, Microsoft Word, Adobe
FrameMaker) with a topic containing a TOC proxy, a TOC is generated and
included in the output. Unless you specify otherwise, the levels of the headings
in the generated TOC are based on the <h1> through <h6> styles in your project
(or other styles where you've entered a value for the mc-heading-level property).
However, this option allows you to use an alternative method, basing the generated TOC on the exact structure that you create in the "outline TOC." For more
l
Unlinked books You can select an option to create headings in a generated
TOC for books that are not linked in your outline TOC. For more information see
the online Help.
l
Remove images You can select an option to remove images from a generated
TOC if you have inserted them into the headings in your topics. For more information see the online Help.
n
Variables (override) The variables that you create and define in the Variable Set
Editor are available to your entire project. However, if you want the definition for a variable to be different in a particular target, you can override the project-level definition
for that target in the Target Editor. For more information see the online Help.
n
View output After you generate a target, you can view the output for it. See "Viewing
Output" on page 468.
n
WebHelp AIR - options (specify) If you are generating WebHelp AIR output, you
can specify several options for it. For more information see the online Help.
n
WebHelp Plus - catalog (enable) If you are generating WebHelp Plus output and
publishing the files to a server running Microsoft Internet Information Services and
Microsoft Indexing Service, you can specify in the Target Editor the catalog that you
are using for the output. In most cases, this will be Web, which is the default value.
However, if you or someone in your company (e.g., network administrator) creates a
custom catalog, you need to enter that name in the field. What is a catalog? Microsoft Indexing Service stores all of its index information in catalogs. A catalog comprises index information and stored properties for a particular
group of file system directories. When Indexing Service is installed with Windows XP,
it automatically builds a catalog, called the System catalog, listing contents of all permanently attached disk drives. The System catalog contains an index for all documents
except certain system and temporary files. If Internet Information Services (IIS) is
- 455 -
MADCAP FLARE
installed, the Indexing Service also creates a Web catalog, which contains an index of
IIS, the default virtual server of the World Wide Web.
n
Word output - mirror margins (enable) Let’s say you create a page layout with
mirror margins on pages (e.g., the odd pages are set up to have a left margin of 2
inches and a right margin of 1 inch, whereas the even pages are set up to have a left
margin of 1 inch and a right margin of 2 inches). In such a case, Microsoft Word is
unable to display the correct margins without a little help. Therefore, you need to enable mirror margins by selecting a single checkbox in the Target Editor. When you generate Word output, you will then see the appropriate margins on each page. For more
n
Word output - multiple documents (create) If you are generating Word output,
you can split the generated output into multiple documents, rather than using the
default, which results in only one document. To create multiple Word documents, you
must also specify chapter breaks at the appropriate places in the TOC (not the TOC
that displays in the Word output, but in the outline TOC used to determine the
printed manual content and structure). This can be done on the Printed Output tab of
the TOC Properties dialog. By specifying chapter breaks, you are letting Flare know
where you want to split the output into new Word documents. For more information
see the online Help.
Note: If you split your output into multiple Word documents, you will not be able
to include a TOC in the printed output. For Word output, you can only include a
print TOC if you generate a single Word document. For more information see the
online Help.
n
XPS output (specify) Microsoft's XML Paper Specification (XPS) is a document format with a markup language that is a subset of XAML for Windows Presentation Foundation. XPS is an alternative to Adobe's Portable Document Format (PDF). By
installing a free add-in download from Microsoft, you can generate output via Microsoft Word to the XPS format. For more information see the online Help.
Please note, however, that you do not need Word 2007 to generate XPS output; you
can send output to XPS directly without first generating Word.
n
XPS output - multiple documents (create) If you are generating XPS output
directly (rather than going through Microsoft Word to produce it), you can split the
generated output into multiple documents, rather than using the default, which results
in only one document. To create multiple XPS documents, you must also specify chapter breaks at the appropriate places in the TOC (not the TOC that displays in the XPS
output, but in the "outline TOC" used to determine the printed manual content and
structure). This can be done on the Printed Output tab of the TOC Properties dialog.
By specifying chapter breaks, you are letting Flare know where you want to split the
output into new XPS documents. For more information see the online Help.
3. After you have edited settings in the editor, click
- 456 -
to save your work.
After you have completed the first part of the development process (i.e., creating and designing content, developing targets), you are ready to build the final output. Of course, you can build the output at any point during the development process, but if you make additional changes to content,
targets, or the look and feel, you will need to build the output again to make sure the changes are
included in the files that you deliver to your end users.
Ways to Build Output
458
Building the Primary Target
459
Building a Single Target
460
Building Output Using a Batch Target
461
Viewing Output
468
- 457 -
MADCAP FLARE
Ways To Build Output
Building the final output is very easy in Flare. It involves generating one or more targets in your
project, usually with just the click of a button or two. Following are the different ways you can build
your final output:
n
Primary target Do this if you are only concerned about building the primary target for your
project. See "Building the Primary Target" on the following page.
n
Single target Do this if you want to build a target that is not designated as your primary
target. See "Building a Single Target" on page 460.
n
Batch target Do this if you want to build and/or publish one or multiple targets in a batch
from the user interface, perhaps scheduled to run at a specific time. See "Building Output
Using a Batch Target" on page 461.
n
Command line/batch Do this if you want to build targets from your operating system's
command line. Using this method, you do not have to open Flare at all. In addition, this
method allows you to build a single target or all targets in your Flare project in one batch.
The best way to use this feature is to create a batch file with the necessary commands in it.
Then you can use a scheduling tool (such as the "Scheduled Tasks" utility in Windows) to run
the batch file automatically whenever you want. This is similar to the "batch target" feature.
However, the command line feature works outside of the Flare interface, is a bit more manual,
and does not support as many processes. For steps see the online Help.
When you build a target, Flare creates output files and places them in a folder named after the target, which is stored in a subfolder of your project called "Output." For example, let's say your project
is stored here: C:\MyProject. In that case, after you generate output, the files would be stored here:
C:\MyProject\Output\MyName\TargetName
Depending on the output type associated with the target, the generated output might consist of
many files.
Note: You do not need to build the target to see how a particular topic will look in the final output. You can always preview topics as you develop your project by clicking
in the local toolbar of the XML Editor. If you click the face of the button, the topic preview is shown based on
the format specified in the primary target. If you click the down arrow, you can select any of the
targets in your project from a menu. The topic preview is then displayed using the output format specified in that target.
- 458 -
Building The Primary Target
Use the following steps if you want to quickly build the primary target for your project.
How to build the primary target
n
OR
n
OR
n
Select Build>Build Primary [Name of Target].
2. After the output files finish generating, a message asks if you want to view the output. Click
either Yes or No. If you select Yes, the generated output opens.
- 459 -
MADCAP FLARE
Building A Single Target
Use the following steps if you want to build a target in your project that is not designated as your
primary target.
How to build a single target
1. In the Project toolbar, click the down arrow in the Build Primary button
available targets are shown. (If you do not see the Project toolbar, select
. The
2. Select Build [name of target].
3. After the output files finish generating, a message asks if you want to view the output. Click
either Yes or No. If you select Yes, the generated output opens.
- 460 -
Building Output Using A Batch Target
Use the following steps if you want to generate and/or publish one or multiple targets in a batch
from the user interface, perhaps scheduled to run at a specific time.
E X AMPLE
Let 's say y ou hav e a p roject wit h 17 t arget s and y ou need t o bu ild and p u blish 12 of
t hose t arget s at t he beginning of each d ay . Rat her t han manu ally bu ild ing and generat ing each of t hese t arget s, y ou can u se a bat ch t arget . Wit hin t his bat ch t arget ,
y ou can select t he "Bu ild " and "Pu blish" op t ions next t o each of t he 12 t arget s. Furt hermore, y ou can u se t he Sched u le t ab in t he bat ch t arget t o sp ecify t hat t he bat ch
should be ru n each night at 2 a. m. When y ou arriv e at t he office each morning, t he
ou t p ut s for t hose 12 t arget s will alread y be generat ed and p laced in t he ap p rop riat e
p ublishing d est inat ion fold ers.
Batch Generate UI/Publish Versus Command Line
The batch target in the Flare interface is similar to the "command line" feature. However, the command line feature works outside of the Flare interface, is a bit more manual, and does not support
as many processes.
- 461 -
MADCAP FLARE
Tasks Associated With Using A Batch Target
Following are the basic tasks associated with using the batch target feature to build and/or publish
output:
n
Create a batch target
n
(Optional) Schedule build or publish processes
n
(Optional) Manually start build or publish processes
C reate A B atch Target
First, you must create a batch target. The batch target is a simple file that points to other targets
and stores information such as whether to build or publish targets, as well as scheduling commands. After creating the file, you can specify its settings in the Batch Target Editor. A batch target
file has an .flbat extension and is stored in the Project Organizer under the Targets folder.
How to create a batch target
1. Select Project>Add Batch Target. The Add Batch Target dialog opens.
n
n
3. In the File Name field, type a new name for the batch target.
4. Click Add.
5. Click OK. The target is added to the Targets folder in the Project Organizer.
6. A message asks if you want to create a scheduled task. Click Yes. The Batch Target Editor
opens to the right.
7. The Targets tab in the editor displays all of the other targets already contained in your
- 462 -
project. Click the Build and/or Publish check boxes next to the targets that you want to be
affected when the batch runs.
Note: In order for targets to be published when the batch runs, you must also create and
associate a publishing destination with the target(s). See "Creating Publishing Destinations" on page 480 and "Associating Publishing Destinations with Targets" on page
483.
to save your work.
- 463 -
MADCAP FLARE
(Optional) Schedule B uild Or Publish Processes
After you create a batch target in the Flare user interface, you can start that batch whenever you
need to (i.e., tell it to start building and/or publishing the related targets). However, you also have
the option of creating scheduled tasks. You might do this if you want your targets to be generated or
published automatically overnight. Scheduled builds are created using the Windows Task Scheduler.
However, the user interface in Flare makes it easier for you to create scheduled tasks without leaving
the application. If you use this scheduling feature, you do not need to have Flare open at the time
the batch runs.
When a scheduled task runs, the command prompt window opens on your computer and minimizes
while the batch runs. This window closes automatically when the batch process is finished. If any
errors or warnings occur during the process, a report is automatically saved so you can review the
messages. You can then open the error report file from the Reports folder in the Project Organizer.
How to schedule build or publish processes
1. From the Targets folder in the Project Organizer, open the batch target file.
2. If a message indicates that you must create a scheduled task, click Yes.
3. In the Batch Target Editor, click the Schedule tab.
4. At the bottom of the tab, click New.
The New Trigger dialog opens.
- 464 -
5. In the Settings area, select how often you want the trigger in the batch to be run. You can
also click in the Start fields to change the beginning date and/or time.
If you select Daily, a field displays so that you can specify a certain number of days for the
process to recur.
If you select Weekly, a field displays so that you can specify a certain number of weeks for
the process to recur. In addition, check boxes are available so that you can select certain days
of the week for the process to run.
If you select Monthly, additional fields are displayed so that you can select certain months
for the process to run, even on specific days during particular months.
6. (Optional) In the Advanced Settings area, you can set any of the following:
n
Repeat task every You can specify if you want the trigger for the batch to run periodically after a certain number of minutes or hours.
n
For a duration of You can specify how long you want the trigger for the batch to be
repeated.
n
Expire You can specify whether the trigger for the batch should stop running after a
certain date.
n
Enabled By default the trigger for the batch will be enabled. However, you can disable
the trigger if necessary. The trigger will remain in the batch file (even though it will not
run while being disabled). You can re-enable it in the future if you want.
7. Click OK.
Tip: Because scheduled tasks in batch targets use Windows Task Scheduler, the settings in that
utility are applied. By default, scheduled tasks will run only if you are logged on. However, you
can change this setting in Windows Task Scheduler so that the batch runs whether you are
logged on or not. To accomplish this, first open Windows Task Scheduler. The steps may be different depending on the operating system. For example, in Windows 7 click the Start button and
select All Programs>Accessories>System Tools>Task Scheduler . Then select Task
Scheduler Library to see a list of your scheduled tasks. In the list select the appropriate task
and click Properties. Click Run whether user is logged on or not (in Windows 7 this is
on the General tab). Click OK. You will be prompted to enter your Windows login password.
When you are finished working for the day, log off your computer (instead of shutting down completely). The task will run as scheduled.
Note: If you create a scheduled task in a batch target, a .job file is automatically created in Windows Task Scheduler. If you delete the batch target from within Flare, the .job file is automatically removed from Windows Task Scheduler. However, if you delete the project or batch
target from Windows (outside of Flare), the .job file remains in Windows Task Scheduler. Therefore, you will need to remove the .job file manually from there.
- 465 -
MADCAP FLARE
(Optional) Manually Start B uild Or Publish Processes
Although you can schedule a batch target to run at a specific time, you can always open the batch
target and manually start the batch.
How to manually start build or publish processes
1. From the Targets folder in the Project Organizer, open the batch target file.
2. In the local toolbar of the Batch Target Editor, click any of the following:
n
Builds and publishes the selected targets (if they have check marks in
the Build and Publish boxes).
Builds the selected targets (if they have check marks in the Build box).
n
Publishes the selected targets (if they have check marks in the Publish
n
boxes).
The Batch Progress dialog shows each target and its build status.
- 466 -
3. (Optional) If any errors or warnings occur during the process, you can save the report file by
clicking Save Log. You can then open the error report file from the Reports folder in the
Project Organizer.
4. (Optional) You can view the output of each built target—by selecting the target row in the
Batch Progress dialog and clicking View Output.
5. (Optional) If you want to open the Windows folder holding the output files that were generated, click Open Output Folder.
6. When the process finishes, click Close in the Build Progress dialog.
Note: When you publish output using a batch target, changed files are replaced and stale files
are always removed.
Note: You cannot use scheduled tasks for batch targets if you are working in trial mode.
- 467 -
MADCAP FLARE
Viewing Output
You can view the generated output for any of the targets in your project. Following are steps for viewing the primary target output, as well as steps for viewing output for the other targets in your
project.
How to view output for the primary target
n
OR
n
Press SHIFT+F6 on your keyboard.
OR
n
Select Build>View Primary [name of target].
2. If the output for the target has not yet been generated or is out of date, a message lets you
know and asks if you want to generate the output. Click Yes. The generated output opens.
How to view output for another target
1. In the Project toolbar click the down arrow in the View Primary button
open the Project toolbar, select View>Toolbars>Project.)
. (To
2. Select View [name of target].
3. If the output for the target has not yet been generated or is out of date, a message lets you
know and asks if you want to generate the output. Click Yes. The generated output opens.
- 468 -
The final piece to developing a Flare project is to distribute your output so that end users can access
it.
Ways to Distribute Output
470
480
Associating Publishing Destinations with Targets
483
Publishing Output to Destinations
484
- 469 -
MADCAP FLARE
Ways To Distribute Output
How you distribute the final output to your users depends on what you are trying to accomplish.
You might want to distribute your output in any of the following ways:
n
Attach to software application You can attach your Flare online output to a software
application so that end users can quickly access the documentation from the Help menu
and/or through context-sensitivity (see page 471).
n
Place on website You can publish your online output files (typically the WebHelp outputs)
on a website or intranet location (see page 474).
n
Put on CD You can copy your output to a location and then burn the files onto a CD (see
page 476).
n
Distribute print-based output You can produce print-based output, which can be printed
or distributed to users electronically (see page 478).
Note: WebHelp Plus is designed to be published to a Web server running Microsoft Internet
Information Services (IIS). For information about WebHelp Plus and making it available to
users, see the online Help.
- 470 -
How to attach Flare online output to a software application
1. Work with the software developer to determine where you will place the output files for the
online output. For example, this can be a public folder on your company's network drive or in
a version control program such as SourceSafe. It simply depends on how your company works
and how the software developer prefers to retrieve your files.
2. After you determine a location for the output files, create a publishing destination (page 480).
3. Associate the publishing destination with the target that you are using (page 483).
4. Build the final output (page 457).
5. Publish the output to the destination (page 484).
6. Inform the software developer:
n
That the output files are now in the appropriate location.
n
That all output files and folders (if more than one file) must be included with the software application. The number of files and folders included in the final output depends
on which output type you are using.
o
DotNet Help This output type requires that all files and folders in your project
file be included for your end users.
DotNet Help is designed to be used on a desktop, rather than being accessed
from a Web server.
Note: If you distribute DotNet Help, you also need to provide the MadCap
Help Viewer to users. This is a free download from MadCap Software.
o
HTML Help There is only one file that needs to be included—the CHM file,
which is [Name of your project].chm (e.g., DoohickeyPro.chm).
HTML Help is designed to be used on a desktop, rather than being accessed
from a Web server.
o
WebHelp This output type requires that all files and folders in your project file
be included for your end users.
WebHelp is designed primarily to be published on a Web server, but it can be
stored locally as well.
o
WebHelp AIR There is only one file that needs to be included—the AIR file,
which is [Name of your project].air (e.g., DoohickeyPro.air).
WebHelp AIR is designed to be used on a desktop, rather than being accessed
from a Web server.
Note: WebHelp AIR also requires users to install Adobe AIR, which can be
downloaded from http://get.adobe.com/air/.
- 471 -
MADCAP FLARE
o
WebHelp Plus This output type requires that all files and folders in your
project file be included for your end users.
WebHelp Plus is designed to be published to a Web server running Microsoft
Internet Information Services (IIS), rather than attached to an application or distributed otherwise. For information about WebHelp Plus and making it available
to users, see the online Help.
n
Which file is the main entry file for the online Help. See "Determining the Output
Type" on page 419.
The main entry file depends on which output type you are using and the file name for
the output (specified in the Target Editor). For example, if you use the "Empty" template, the default main entry file for each output type is as follows: Manual.mchelp for
DotNet Help, Manual.chm for HTML Help; Default.htm for WebHelp, WebHelp Plus,
and WebHelp Mobile; and Default.air for WebHelp AIR. You can change the main entry
file name for a particular output by opening the target and typing the name in the Output File field of the Target Editor.
7. At this point, it is up to the software developer to "attach" the online output to the application. After the developer creates a build of the application containing the online output, you
should test it thoroughly.
See the online Help for more details about the information that you need to provide for the
developer (depending on the output type you generated). Following are the names of the relevant topics in Flare’s online Help. Provide the information in these topics for the developer.
DotNet Help:
n
CSH Calls for DotNet Help
Provide the developer with the information in the following topics:
- 472 -
o
CSH Calls for DotNet Help—Developers
o
HelpViewerClient API
o
HelpViewerEmbeddedClient API
o
IEmbeddedHelpSystem API
o
ICSHIDProvider API
o
Command Line
HTML Help:
n
CSH Calls for HTML Help
Provide the developer with the information in the following topic:
o
CSH Calls for HTML Help—Developers
WebHelp and WebHelp Plus:
n
CSH Calls for WebHelp and WebHelp Plus
o
CSH Calls for WebHelp and WebHelp Plus—Developers
WARNING: Software developers often create scripts that "grab" your output files from their
location automatically. Therefore, if you publish the output files to a different location, or if you
change the name of the destination folder (even by one character), their script will not work. So
always maintain close communication with the software developer when publishing your output files or when you make any changes to the publishing destination.
- 473 -
MADCAP FLARE
How to place the Flare output in a folder or on a website
1. Work with your manager, network administrator, website administrator, or other responsible
individuals to determine where you will place the output files.
2. Work with the appropriate individual(s) to decide how the end users will access the output.
For example, will they click a link on a website? Whatever decision is made, someone (typically a Web designer or administrator) usually creates a link for the end user to access the
output. Your job is typically to make sure the appropriate individuals who create this link
know which file is the main entry file for the online output.
The main entry file depends on which output type you are using and the file name for the output (specified in the Target Editor). For example, if you use the "Empty" template, the default
main entry file for each output type is as follows: Manual.mchelp for DotNet Help, Manual.chm for HTML Help; Default.htm for WebHelp, WebHelp Plus, and WebHelp Mobile; and
Default.air for WebHelp AIR. You can change the main entry file name for a particular output
by opening the target and typing the name in the Output File field of the Target Editor.
The number of files and folders included in the final output depends on which output type
you are using:
o
WebHelp This output type requires that all files and folders in your project file be
included for your end users.
WebHelp is designed primarily to be published on a Web server, but it can be stored
locally as well.
o
WebHelp Mobile This output type requires that all files and folders in your project
WebHelp Mobile is designed to be published to a Web server where users with mobile
devices may access the output files, rather than attached to an application or distributed otherwise. Think of your output files as a website. A user with a mobile device
can, for example, open a mobile browser on the device and enter the URL that points to
your main output entry file.
o
WebHelp Plus This output type requires that all files and folders in your project file
WebHelp Plus is designed to be published to a Web server running Microsoft Internet
Information Services (IIS), rather than attached to an application or distributed otherwise. For information about WebHelp Plus and making it available to users, see the
online Help.
3. Gather additional information that you will need from the appropriate individuals (e.g., Web
administrator, system administrator). This might include the following, depending on where
you are publishing the output files:
- 474 -
n
The host name (or ftp address) if you are publishing the output to a website (e.g.,
ftp.acme.com).
n
The specific folder where the output files should be published.
n
The appropriate port.
n
Any user name or password required for you to publish the files.
4. After you determine a location to place the output files and have gathered the necessary information, create one or more publishing destinations (page 480).
End users should now be able to open the output, as long as the other individuals involved
(e.g., Web administrator, system administrator) have completed their tasks (e.g., create the
website link to the entry file for your output.) If you plan to create context-sensitive Help
(CSH) calls from Web links to parts of your output, use the information in the following topics:
WebHelp and WebHelp Plus:
n
CSH Calls for WebHelp and WebHelp Plus
o
CSH Calls for WebHelp and WebHelp Plus—Developers
WebHelp Mobile:
n
CSH Calls for WebHelp Mobile
o
CSH Calls for WebHelp Mobile—Developers
- 475 -
MADCAP FLARE
How to put the Flare output on a CD
1. Work with individuals who are responsible for creating the CD to determine where you will
place the output files (unless you are responsible for creating the CD).
2. After you determine a location to place the output files, create a publishing destination (page
480).
6. Inform the individual responsible for creating the CD:
n
That the output files are now in the appropriate location.
n
That all output files and folders (if more than one file) must be included in the CD. The
number of files and folders included in the final output depends on which output type
you are using.
o
DotNet Help This output type requires that all files and folders in your project
DotNet Help is designed to be used on a desktop, rather than being accessed
from a Web server.
Note: If you distribute DotNet Help, you also need to provide the MadCap
Help Viewer to users. This is a free download from MadCap Software.
o
HTML Help There is only one file that needs to be included—the CHM file,
which is [Name of your project].chm (e.g., DoohickeyPro.chm).
HTML Help is designed to be used on a desktop, rather than being accessed
from a Web server.
o
WebHelp This output type requires that all files and folders in your project file
WebHelp is designed primarily to be published on a Web server, but it can be
stored locally as well.
o
WebHelp AIR There is only one file that needs to be included—the AIR file,
which is [Name of your project].air (e.g., DoohickeyPro.air).
WebHelp AIR is designed to be used on a desktop, rather than being accessed
from a Web server.
Note: WebHelp AIR also requires users to install Adobe AIR, which can be
downloaded from http://get.adobe.com/air/.
o
- 476 -
WebHelp Mobile This output type requires that all files and folders in your
WebHelp Mobile is designed to be published to a Web server where users with
mobile devices may access the output files, rather than attached to an application or distributed otherwise. Think of your output files as a website. A user
with a mobile device can, for example, open a mobile browser on the device and
enter the URL that points to your main output entry file.
o
WebHelp Plus This output type requires that all files and folders in your
WebHelp Plus is designed to be published to a Web server running Microsoft
Internet Information Services (IIS), rather than attached to an application or distributed otherwise. For information about WebHelp Plus and making it available
to users, see the online Help.
n
Which file is the main entry file for the output. See "Determining the Output Type" on
page 419.
The main entry file depends on which output type you are using and the file name for
the output (specified in the Target Editor). For example, if you use the "Empty" template, the default main entry file for each output type is as follows: Manual.mchelp for
DotNet Help, Manual.chm for HTML Help; Default.htm for WebHelp, WebHelp Plus,
and WebHelp Mobile; and Default.air for WebHelp AIR. You can change the main entry
file name for a particular output by opening the target and typing the name in the Output File field of the Target Editor.
7. At this point, it is up to the responsible individual to burn the output files to the CD and provide a way for end users to access it easily. After the individual creates the CD, you should
test it thoroughly before it is distributed to end users.
- 477 -
MADCAP FLARE
How to distribute print-based output
1. You can simply open your Output folder to retrieve the files manually, or you can use Flare's
publishing feature to automatically send a copy of the output files to another location (e.g., to
a network folder or a website).
To retrieve the local files manually:
n
Select Build>Open Output Folder, and navigate to the subfolder named after the
target you generated.
To use the publishing feature:
a. Create a publishing destination for your printed manual (page 480).
b. Associate the publishing destination with the appropriate target that you are using
(page 483).
c. Build the final output for that target (page 457).
d. Publish the output to the destination (page 484).
Note: You can also use a batch target to generate and/or publish multiple targets in a single batch file automatically. See "Building Output Using a Batch Target" on page 461.
2. Now you (or others) can print the manual from the destination and distribute it to end users.
You can also provide the document in electronic form to end users.
Which output files do you need to be concerned with? It depends on the output type.
PDF:
PDF output consists of a file with a .pdf extension that you can print or distribute to users.
XPS:
XPS output consists of a collection of XPS files that you can print or distribute to users. This
includes:
n
A file with an .xps extension. This is the file that contains the consolidated topic content from your project. This is the main file and the only one that is essential. This is
the file that you would provide to a printer or distribute to end users.
n
If you want users to download an XPS document from a server, you need to enable the server
to do this by registering the MIME types and file extensions. For steps see the online Help.
XHTML:
XHTML consists of a collection of XHTML files that you can print or distribute to users. This
includes:
n
- 478 -
A file with an .htm extension. This is the XHTML file that contains the consolidated
topic content from your project.
n
A file with an .mcbook extension. This file is used to display the chapters in the MadCap Book Viewer.
n
If you want to make XHTML output accessible for others, you need to include all of the files
in the output mentioned in this list. Otherwise, when they view the output, certain elements
(e.g., images) might be missing from the pages.
Word:
Depending on your settings, Microsoft Word consists of one or more XML, DOC, DOX, XPS,
or PDF files that you will distribute to users.
FrameMaker:
Depending on your settings, Adobe FrameMaker consists of one or more BOOK, FM, or PDF
files that you will distribute to your users.
Note: When you build Word or FrameMaker output, Flare creates an extra folder called
Resources (if your project contains ancillary files, such as pictures). If you want to embed the
images in your document, you will need to do so manually in Word or FrameMaker. Otherwise,
if you move the Word or FrameMaker output files to another location than your Output folder,
you must remember to also move the Resources folder. Without that folder in the proper location, the referenced images will no longer be displayed in the output files. If you convert the
Word or FrameMaker files to PDF, the images will then be incorporated into the PDF file, and
you can move that single file anywhere you like.
- 479 -
MADCAP FLARE
When you build output from your project, Flare produces the output files and places them in a
folder with your project files. Publishing simply has to do with copying those output files and placing them in a location where others can access them, such as on a network, a website, or a SharePoint server. Of course, you can manually copy the output files from your project folder and paste
them wherever you'd like, or you can use FTP software to transfer them to a remote server. Flare's
publishing feature is simply a way to do this more quickly and easily.
There is a little bit of setup work to complete initially when it comes to publishing your output. But
once you are finished with the setup, the ongoing act of publishing your output files can be done
with the click of a button.
The first step to setting up your project for publishing output is to create a publishing destination.
You can create as many publishing destinations in your project as necessary, depending on how
many locations you need to send your output files.
How to create a publishing destination
n
If you want to use an existing destination:
a. Double-click the Destinations folder. The existing publishing destinations are
shown. Depending on the project template you select, Flare may provide you
with an initial destination to help get you started.
b. Double-click the destination that you want to open. The destination opens in its
own page in the Destination Editor. (If you want, you can also rename the destination to fit your needs.)
OR
n
If you want to create a new destination:
a. Right-click the Destinations folder and select Add Destination. The Add Destination dialog for destinations opens.
b. In the Source area select one of the following:
n
- 480 -
New from template This lets you choose either a factory template file
or one of your own customized template files as a starting point. The new
file will take on all of the settings contained in the template. If you want
to use a factory template provided by Flare, expand the Factory Templates folder and click on a template file. If you want to use your own
customized template file, expand the appropriate folder and click on a
if you want to open the Template Manager. This
lets you manage any of your template files (e.g., add new templates,
enter descriptions for templates). For more information see the online
Help.
n
New from existing This lets you choose an existing file of the same
type—that you've already created and stored somewhere—as a starting
point for your new file. As with template files, your new file will take on
all of the settings contained in the file you select. To use this option, click
the browse button
, use the dialog that opens to find a file, and double-click it.
c. In the File Name field, type a new name for the destination (e.g., Doohickey
Staging website, Doohickey Live website, Network Documentation Folder).
d. Click Add. The destination is added to the Project Organizer and opens in its
own page in the Destination Editor.
3. Click in the Type drop-down field in the Destination Editor and select either FTP or File
System, depending on which method you want to use to publish the output files. Use the
FTP (file transfer protocol) option if you want to publish output files to another computer
over a TCP/IP network. Use the File System option if you want to publish the output to a location on your computer or to another drive on a network. If you have previously connected to a
SharePoint server, you can use the "File System" type to choose a folder on that server as the
destination.
4. Complete the rest of the fields in the Destination Editor.
n
(Optional) Comment You can use this field to provide a description of the destination so that its purpose is clear.
n
Host Name Enter or select the name of the remote server or the computer where the
output files will be published. If you use the FTP type, the host name will look something like this: ftp.acme.com. If you use the File System type, this field is disabled.
n
Port Enter the port that you will use to connect to the remote server. Typically, you
can obtain the port from your network administrator. This option is disabled if you use
the File System type.
n
Anonymous Login Select this check box if you want to publish to the server without
being required to enter a user name or password. (You may need to check with your network administrator to determine if this is allowed.) This option is disabled if you use
the File System type.
n
Login Credentials Select this button to open the Log On As dialog. You can then
enter the user name and password required for accessing the server to which you are
publishing. If you do not enter the user name and password at the point, a dialog will
open later when you actually publish the output, asking for the user name and password. This option is disabled if you use the File System type.
n
Directory Enter the exact location where the output files will be published. If you use
- 481 -
MADCAP FLARE
the FTP type, you might enter something like this: public_ html/Help/DoohickeyPro.
You can also leave the default setting of "public_html" if you are publishing to the root
directory on the server.
Note: When you publish your output, only the files and subfolders within your target's output folder are sent to the destination. The target output folder itself is not
included. For example, let's say you have a target named "AdvancedOutput." If
you want the output to be placed in a destination with the same folder name, you
need to create the "AdvancedOutput" folder at the final location first. Then in your
publishing destination file, you can point to that exact folder. When you publish
the output, the necessary files will automatically be placed inside it.
n
If you use the File System type, you can click this button to select a location. The
Directory field will then populate automatically for you. This button is disabled if you
use the FTP type.
n
"View" Url You can enter or select an .http address in this field to be used for viewing the published files. This field is optional and is for your own internal purposes.
n
Open in Default Browser Select this button if you want to open the URL in your
Internet browser window.
n
Upload Only Changed Files Select this option if you want Flare to republish only
the files that have changed. This can save significant time.
n
Remove Stale Files Select this option if you want Flare to identify files that were
previously published but are no longer needed. Flare will then remove such files from
the destination.
- 482 -
to save your work.
Associating Publishing Destinations With Targets
After you create a publishing destination, you need to associate it with a target that you plan to
build. You can associate the same publishing destination with as many targets as you want.
How to associate a publishing destination with a target
The existing targets are shown.
3. Double-click the target that you want to associate with the destination.
The target opens in its own page in the Target Editor.
4. Click the Publishing tab.
All publishing destinations that have been added to the project are displayed. If a destination
contains a check mark next to it, that means it is associated with the target. If it does not contain a check mark, it is not yet associated with the target.
5. Click the check box next to any destinations that you want to associate with the target.
A check mark appears next to any destinations that you select.
to save your work.
- 483 -
MADCAP FLARE
Publishing Output To Destinations
After you create a publishing destination and associate it with a target, you are ready to publish
your output to the destination.
You can publish output in the following ways:
n
Primary target You can quickly publish your primary target.
n
Single target You can publish a specific single target.
n
Batch target You can publish (and generate) multiple targets by using a batch target. You
can even create a scheduled task so that the batch runs at a specific time (e.g., nightly at 3
am). For steps on using this method, see "Building Output Using a Batch Target" on page
461.
How to publish your primary target to a destination
1. If your output is not up to date, rebuild it. See "Building Output" on page 457.
n
OR
n
In the Target Editor for that target, click
.
OR
n
Press CTRL+F6 on your keyboard. OR
n
Select Build>Publish Primary: [Name of Target]. 3. If necessary, change any of the options in the Publish Target dialog. n
Publish Add or remove the check mark next to any destinations (depending on
whether you want to publish to that destination or not).
n
n
the destination.
4. Click Start Publishing. 5. If a user name and password are required and you have not already provided them in the Destination Editor, enter them in the dialog that opens. 6. After the files are successfully published, a dialog opens, asking if you want to view the log
(which lists the files that have been uploaded). Click Yes if you want to see it, and close the
log when you are finished.
7. In the Publish Target dialog, click Close. - 484 -
How to publish a single target to a destination
1. If your output is not up to date, rebuild it. See "Building Output" on page 457.
4. Right-click on the target that you want to build. In the context menu, select Publish [Name
of Target].
5. If necessary, change any of the options in the Publish Target dialog.
n
Publish Add or remove the check mark next to any destinations (depending on
whether you want to publish to that destination or not).
n
n
the destination.
6. Click Start Publishing. 7. If a user name and password are required and you have not already provided them in the Destination Editor, enter them in the dialog that opens. 8. After the files are successfully published, a dialog opens, asking if you want to view the log
(which lists the files that have been uploaded). Click Yes if you want to see it, and close the
log when you are finished.
9. In the Publish Target dialog, click Close. - 485 -
MADCAP FLARE
- 486 -
Index
Audio
A
inserting
picture
411
126, 207, 213, 292, 298, 448
PDF
WebHelp
448
448
Accordions
output window
411
Adobe Flash
183, 185, 188
Adobe FrameMaker
430
importing
output
passthrough markers
Adobe PDF
26, 38, 41
414, 417, 430
41
414, 417, 428-430, 452
accessibility
external link
multiple documents
pictures
AIR file
448
216
452
452
420, 423
Alias files
104-105
adding
associating with targets
targets
104
122
448
Alignment
paragraphs
Alt
Alternate text
Analyzer
Anonymous login
ASF file
79, 197
Auto Suggestion
About box
Accessibility
61, 78
403
See Alternate text
126, 207, 213, 292, 297
See MadCap Analyzer
481
78, 185
snippets
324
AutoFit behavior
333
Auto-indexes
166
Auto-numbers
364
CH
chapters
cross-references
examples of formats
figure captions
file commands
float left
float right
flow
format commands
formats
GH
inside head
inside tail
lists
outside frame
outside frame left side
outside frame right side
outside head
outside tail
page commands
page numbering
paragraphs
positioning
sections
styles
table headings
text commands
volumes
ASP.NET
422
Auto-reimport
ASPX file
451
AVI file
ASX file
185
AU file
78
368
352, 364, 368
201
367
365, 371
374
379
379
343, 366
374
366, 373
367
379
379
365
379
379
379
379
379
374
365
365, 403
379
352, 364
366
365, 371
374
352, 364, 367
35, 40, 49
185
- 487 -
"Background" through "Characters"
Building
B
Background
color
paragraphs
pictures
text boxes
84, 195, 350
403
287
350
Bars
structure
9-10, 403
Batch
output
targets
4, 458, 461
4, 461, 484
Binary index
creating
410
Binary TOC
creating
BMP file
410
62, 283, 289, 452
Body
drop-down text
proxy
BOOK file
225
178
38, 430
197
indexes
inserting
410
215
Borders
83, 194, 336, 349
403
287
349
Breadcrumbs
proxy
Browse sequences
adding
creating
editing
master
opening
skins
targets
178, 262
61, 86
87
89
90
338, 340
88
92
93, 448
Browser
DOCTYPE declaration
WebHelp
WebHelp Plus
- 488 -
Bullet
95
Bulleted lists
See Lists
Buttons
HTML Help
410, 449
C
Captions
auto-numbers
output window
table
Capture
365, 371
411
333
See MadCap Capture
Cascading style sheets
Bookmarks
color
paragraphs
pictures
text boxes
batch target
4, 458, 461
output
457
performance
452
primary target
415, 458-459
single target
448, 458, 460
targets using command line
458
448
411
411
36, 44, 50, 362
Cent
96
CH
368
Chapnum
368
Chapters
auto-numbers
breaks
variables
352, 364, 368
343, 452, 456
63, 352
Characters
bullet
cent
copyright
degree
double dagger
ellipses
euro
greater or equal
inserting
m-dash or em dash
n-dash or en dash
non-breaking space
not equal
plus/minus
pound
quick characters
registered trademark
trademark
Unicode
95
96
95
95
96
96
96
96
61, 95
96
96
95
96
96
96
94
95
95
94
"Check in" through "div tag"
yen
96
Check in
317
Check out
316
CHM
See HTML Help
Classes
See Styles
Color
100, 104-105, 112, 124
97
112, 453
124
112
Contributions
4
Converting
background
border
condition tag
84, 195, 350
83, 194, 336, 349
440
Columns
glossary terms to links
141, 449
online features to printed output
453
topics to XHTML
30-32
Copyright
breaks
condition tag
lists
MadCap Feedback
publishing destination
Compiling
Cross-references
197, 200, 202, 210
440
383, 392
410-411
481
auto-numbers
editing
inserting
styles
updating
201
202
202-203
205, 211
202, 212
See Building
Concepts
198
inserting
227
Condition tags
415, 437
color
comments
content
creating
files
image files
MadCap Capture
MadCap Mimic
page layouts
renaming
snippets
style sheets
tag sets
targets
text
topics
440
440
417, 438, 441, 443
417, 438-439
445
445
437
437
445
439
323, 445
445
438
417, 438, 447-448
442
445
Content
condition tags
editing and formatting
files
folder
Content Explorer
443
363
27
64, 451
13
Context-sensitive Help
95
403
Comments
alias files
header files
identifiers
planning
skins
testing
topic IDs
61, 97
104-105
100, 102-103, 110, 123
CSH
See Context-sensitive Help
CSS file
36, 44, 50
D
Default topic
Degree
See Startup topic
95
Destinations
anonymous login
comments
creating
directory
host name
login credentials
optional view URL
port
publishing output
targets
481
481
480
481
481
481
482
481
453, 484
483
Directional synonyms
307
Directory
481
Distributing output
469
DITA
DITA file
DITAMAP file
importing
output
relationship tables
div tag
4, 414, 417, 419
48
48
26, 48
430
199, 238, 245, 249251, 260, 453
346
- 489 -
"DOC file" through "FLMSP file"
DOC file
Dockable windows
DOCTYPE
DOCX file
DotNet Help
distributing
embedded Help
language
main entry file
performance
Double dagger
33, 429
21
448
Extensible Markup Language
Extensions
custom
33, 414, 417, 429
External files
414, 417, 419, 423
hyperlinks
471, 476
419
419
472, 474, 477
452
hyperlinks
Drop-down text
198
Feedback
225
225
225
225, 287
225
198
198
197
197
E
35, 40, 49, 449
Ellipses
96
Em dash
96
Embedded Help
419
EMP file
62, 283, 289, 452
En dash
96
Endnotes
EPS file
Equations
Euro
61, 138-139
62, 283
61, 125-126
96
EXE file
420
Expanding text
198
heading
hotspot
inserting
unbinding or removing
EXPS file
- 490 -
comments
enabling
MadCap Feedback
search
synonyms
423
410-411
449
409-410
303
303
Figure captions
Dynamic effects
DotNet Help
197, 216
96
F
Easy Sync
197, 216
External resources 4, 27, 61, 127, 133-134,
136-137
403
drop-down text
expanding text
popups
togglers
451
External Help systems
Drop caps
body
heading
hotspot
inserting
See XML
226
226
226
226
62, 283, 289, 452
auto-numbers
File Transfer Protocol
365, 371
474, 481
Files
Analyzer
condition tags
content
extensions
lowercase names
output
project
source control
tags
underscores
27
445
27
451
451
27
27
27
4
451
FLAIX file
166
FLALI file
104
Flash
See Adobe Flash
FLBAT file
462
FLBRS file
86-87
FLGLO file
141
FLIMP file
33, 37
FLIMPDITA file
48, 50
FLIMPFL file
FLIMPFM file
55
38, 47
FLIXL file
170, 173
FLMSP file
178, 181
"Floating" through "Highlighted"
Floating
Global Project Linking
objects
pictures
text boxes
windows
400
288
348
21
FLPGL file
275
FLPRJ file
27, 52
FLSNP file
322
FM file
38, 430
Folders
content
lowercase names
underscores
64, 451
451
451
Fonts
381
editing
font family lists
font sets
selecting
381
381
381
381
Footers
62, 275, 451
Chapter Number variables
Heading variables
master pages
proxies
Running Head variables
Section Number variables
Volume Number variables
Footnotes
63, 352
63, 352
178, 180
178
63, 352
63, 352
63, 352
61, 138-139
Formatting
auto-numbers
inline
local
paragraphs
topic content
FrameMaker
Framesets
FTP
See Adobe FrameMaker
279, 281, 287
85, 196, 207, 213, 219-220,
223
See File Transfer Protocol
G
Generating
GH
GIF file
Glossaries
adding
converting terms
creating
expanding text links
glossary term links
Glossary Terms window
hyperlinks
master pages
opening
popup links
proxies
skins
targets
text definitions
topic definitions
Graphics
Greater or equal
See Building
367
62, 283, 289, 453
14
62, 141
142
141, 449
143
143, 145
144-145
144
143, 145
146
142
143, 145
178
145
145, 449
141, 143
141, 143
See Pictures
96
H
HDP file
62, 283
Header files
100, 110
adding
alias files
exporting
importing
102
104
123
103
Headers
366, 373
363
363
403-404
363
Frames
page layouts
Global toolbars
4, 54
Heading variables
master pages
proxies
62, 275, 451
63, 352
63, 352
178, 180
178
63, 352
63, 352
63, 352
Heading
drop-down text
expanding text
positioning
side
text boxes
variables
HHP file
225
226
382
382
382
63, 352
26, 31
Highlighted
variables
354
- 491 -
"Horizontal lines" through "Language support"
Horizontal lines
See Rulers (horizontal
lines)
Host name
481
Hotspot
drop-down text
expanding text
text hyperlinks
text popups
toggler
hr tag
HTM file
225
226
213
222
224
Indent
299
Indexes
64, 183-184, 420-423, 430, 451
HTML file
451
importing
69
HTML Help
414, 417, 420, 423
binary indexes
binary TOCs
buttons
distributing
external links
importing
indexes
main entry file
navigation pane
printing topics
TOC
toolbars
Viewer
410
410
410, 449
471, 476
197, 216
26, 31-32
410
472, 474, 477
410
449
410
410-411
423
Hyperlinks
197
external
hotpsot
inserting
197, 216
213
213
214
Hyphenation
403
I
Identifiers
100, 104, 112, 124
creating and assigning
options
Images
112
105
See Pictures
Importing
auto-reimporting
DITA files
Easy Sync
files from projects
FrameMaker documents
- 492 -
header files
HTML files
HTML Help files
HTML Help projects
RoboHelp projects
source control projects
Word documents
35, 40, 49
26, 48
449
4, 54
26, 38, 41
103
69
26, 32
31
26, 30
26, 51
26, 33
paragraphs
auto-indexes
binary
bookmarks
Index Entry Mode
index links
keywords
markers
proxies
search
skins
Indexing services
403
62, 147
166
410
410
148
150, 169
150, 152, 156, 162
150
178
450
177
See Microsoft Indexing
INI file
51
Initial caps
Inline formatting
Interface
403
See Local formatting
See Workspace
Internet Information Services
422
J
JavaScript
63, 300
WebHelp
411
JPEG file
62, 283, 289, 453
JPG file
62, 283
JScript
63, 300
K
Keyword links
inserting
199
230
Keywords
indexes
150, 152, 156, 162
L
Language support
DotNet Help
4
419
"Layouts" through "M-dash"
interface
spell check
Unicode
WebHelp
WebHelp Plus
Layouts
419-421, 450
28
1, 94
420-421, 450
450
See Page layouts
Line spacing
Lines
403
See Rulers (horizontal lines)
Links
4
MadCap Feedback
409-410
MadCap Help Viewer
419, 423
MadCap Mimic
condition tags
movie links
437
186
MadCap Movie Viewer
182-183
Map files
See Header files
338
Map IDs
See Identifiers
62, 197
Margins
Linking
tables of contents
MadCap Contributor
197, 216
213
213
213
Microsoft Word
page layouts
paragraphs
pictures
456
456
403
288
Linux
421
Mark of the Web
450
Lists
383
Markers
external
hotspot
inserting
quick
adding notes or comments
auto-numbers
continuing sequence
merging
multi-level
proxies
restarting numbering
reversing
simple
sorting
styles
unbinding
Local formatting
363
Local toolbars
Localization
383, 392
365
383, 389
383, 390
383, 386
288, 331
383, 396
383, 397
383, 385
383, 398
383
383, 399
18
See Language support
Login
481
Lowercase
451
421
MadCap Analyzer
files
Master browse sequence
Master page layouts
Master pages
Master style sheets
MathML
27
437
288
287, 294
288
338, 340
451
62, 178
adding
creating
disabling use
glossaries
headers and footers
Heading variables
opening
page numbers
proxies
snippet conditions
targets
MCHELP file
MadCap Capture
condition tags
editing pictures
inserting screen captures
launching
150
353
178-179
178
450
146
178, 180
63, 352
181
344
178, 180
63, 352
323
181, 450
454
Master table of contents
M
Macintosh
indexes
variables
338, 340, 345,
454
61, 125-126
419, 423, 472, 474, 477
MCMOVIE file
182, 186
MCMOVIESYS file
182, 186
MCMV file
M-dash
186
96
- 493 -
"Mediums" through "Orphans"
Mediums
Moving
targets
454
Menus
14
Merging
lists
tables of contents
383, 390
338
Microsoft HTML Help
See HTML Help
Microsoft Indexing
422
Microsoft SharePoint
4, 27, 310, 313-314,
318, 320-321
check in
check out
Microsoft Silverlight
403
403
288
21
MP3 file
78
MP4 file
78, 185
MPA file
78
MPE file
185
MPEG file
78, 185
317
316
MPG file
78, 185
MPJ file
26
183
Multi-authoring
Microsoft Team Foundation Server
26
Microsoft Visual SourceSafe
26
Microsoft Windows 7
block content
paragraphs
pictures
window panes
4, 26, 28, 51, 316-317
N
304, 422
Navigation links
62, 197
Microsoft Windows Server 2003
422
Microsoft Windows Server 2008
422
bookmarks
concepts
cross-references
215
227
197, 200, 202-203,
210, 212
225
226
216
219-220
230
232
261
213
222
224
223
Microsoft Windows Vista
Microsoft Windows XP
Microsoft Word
422, 455
430
importing
mirror margins
multiple documents
output
Microsoft XPS
74, 419, 422
26, 33
456
456
414, 417, 429
289, 414, 417, 429-430,
452, 456
multiple documents
456
MID file
78
MIDI file
78
MIF file
38
Mimic
See MadCap Mimic
Mimic Movie Format
182
MIMOV file
186
Mini-TOC
proxies
MIPRJ file
MOTW
MOV file
Movies
inserting
- 494 -
178, 267
186
See Mark of the Web
185
62, 182
186, 188, 197
drop-down text
expanding text
external links
image hyperlinks
keyword links
related topics links
shortcut controls
text hyperlinks
text popups
togglers
topic popups
Navigation pane
N-dash
Next style
Non-breaking space
Numbered lists
410-411
96
403
95
See Lists
O
Object positioning
floating
400
400
Online output
419
Optional view URL
482
Orphans
404
"Output" through "Performance"
Output
413
accordions
409, 411
Adobe Flash
183
auto-numbering
366
batch
4, 458, 461
browser settings
411
building targets
4, 448, 457-461
buttons for HTML Help
410, 449
captions
411
Content folder
451
custom file extensions
451
distributing
469
DITA
430
DOCTYPE declaration
448
DotNet Help
409, 419
files
27
FrameMaker
430
HTML Help
409, 420
look and feel
361
lowercase file names
451
main entry file
423, 430, 450
Microsoft Silverlight
183
Mimic Movie Format
182
navigation pane
410-411
online
419
PDF
428, 452
performance
452
previewing
409
printed output
419
publishing
453, 484
size
409
tables of contents
410
tabs
409
toolbars
409-411
types
414, 417, 419, 432, 451
underscores in file names
451
viewing
455, 468
WebHelp
409, 420
WebHelp AIR
420
WebHelp Mobile
421
WebHelp Plus
409, 422, 455
web-safe images
452
Word
429
XHTML
428
XPS
429, 456
Page breaks
paragraphs
Page footers
proxies
178
62, 275, 451
proxies
178
Page layouts
62, 275
63, 352
condition tags
445
frames
279, 281, 287
Heading variables
63, 352
margins
456
master
451
mirroring pages
456
page numbers
344
63, 352
63, 352
specifying
344
63, 352
Page numbering
62, 275, 279, 281, 344,
451
auto-numbers
365
Paragraphs
alignment
auto-numbers
background
borders
drop caps
formatting
hyphenation
indentation
initial caps
lists
margins
moving
orphans
page and column breaks
positioning
short line elimination
spacing
widows
Passthrough markers
PDF
Padding
Performance
288
350
62, 275, 451
Page headers
P
pictures
text boxes
403
targets
403
365-366, 403
403
403
403
403
403
403
403
383, 392
403
403
404
403
403
403
403
404
41
See Adobe PDF
452
- 495 -
"Pictures" through "Publishing"
Pictures
62, 283
adding
background
borders
capturing
deleting
editing
floating
hyperlinks
Image Map Editor
image maps
inserting
list of
MadCap Capture
margins
moving
opening
padding
PDF
positioning
raster
resizing
styles
tables of contents
thumbnails
topic background
vector
web-safe
wraparound text
287
287
287
287, 294
287-288
288
288
197, 219, 287
220
220
287, 290, 294
288
288
288
288
288
288
452
288
62, 283
288, 452
288, 452
455
288
287
62, 283
452
288
Plus/minus
PNG file
96
62, 125, 283, 289, 453
Popups
hotpsot
inserting
Port
197
222
222-223
223
481
Positioning
auto-numbers
headings
objects
output window
paragraphs
pictures
text boxes
Pound
379
382
400
409
403
288
348
96
- 496 -
building
publishing
setting
viewing output
409
458
29, 415
415, 458-459
415, 484
417, 436
415, 468
Print
topics
Print-based output
chapter breaks
distributing
FrameMaker
lists of elements
multiple documents
PDF
proxies
tables of contents
Word
XHTML
XPS
449
419, 453
452, 456
478
430
288, 331
452, 456
452
288, 331
343, 455
429
428
429
Project Organizer
12
Project toolbar
16
Projects
59
creating
files
Global Project Linking
importing
master style sheets
opening
skins
source control
starting
tables of contents
26, 28, 48
4, 54
4, 54
4, 54
454
26, 53
406
28, 453
25
345
Proxies
body
breadcrumbs
glossaries
indexes
lists
master pages
mini-TOC
page footers
page headers
relationship
tables of contents
PS file
Previewing
skins
topics
Primary target
178
178, 262
178
178
288, 331
178, 180
178, 267
178
178
245, 260
178
62, 283
Publishing
batch targets
484
"QR code" through "Skins"
destinations
targets
453, 480, 483-484
415, 453, 483-484
Screen tip 80, 85, 126, 196, 207, 213, 219220, 223, 292, 297
Scripts
Q
63, 300
inserting
QR code
63, 295-296
QT file
185
Quick characters
inserting
specifying
61, 95
94
Quick links
hyperlinks
213
QuickTime
185, 188
Quirks mode
448
301
Search
63, 302
including stop words
indexes
MadCap Feedback
non-XHTML files
search filters
skins
synonyms
WebHelp Plus
Section 508
302
450
303
304
453
306
303, 307
304
126, 207, 213, 292, 298, 448
Sections
R
Raster images
62, 283
Redacted text
453
Registered trademark
95
Related topics links
198
inserting
232
Relationship links
Relationship tables
199, 260
199, 238, 245, 249251, 260, 453
styles
248
Resizing
elements in workspace
pictures
Reviews
Reviews toolbar
RTF file
4
17
26, 30
33
Rulers (horizontal lines)
63, 299
63, 352
S
Schemas
DITA
Screen captures
352, 364
344
63, 352
See Also links
See Concepts
Selectors
See Styles
Server
MadCap Feedback
WebHelp Plus
SharePoint
4, 430
See Pictures
409-410
422
See Microsoft SharePoint
Short line elimination
403
Shortcut controls
199
inserting
21
288, 452
RoboHelp
importing
auto-numbers
breaks
variables
Side headings
Single-sourcing
261
382
4, 54, 413
Size
pictures
text boxes
Skins
accordions
adding
browse sequences
browser settings
buttons for HTML Help
captions
context-sensitive Help
editing
Feedback comments
generating
glossaries
indexes
288
348
405
409, 411
406
92
411
410, 449
411
112, 453
409
410-411
453
145
177
- 497 -
"Snippets" through "Tables of contents"
language
navigation pane
opening
previewing
search
size
Standard
styles
tables of contents
tabs
targets
toolbars
WebHelp Mobile
Snippets
450
410-411
408
409
306
409
91, 344, 409
409
345, 410
409
412, 453
409-411
91, 344, 409
4, 63, 322
adding
Auto Suggestion
block
condition tags
creating
editing
inserting
text
327
324
323
323, 445
325-326
330
328
323
Sorting
398
Source control
4, 27-28
bind
28
get latest version
453
importing projects
26, 51
Microsoft Team Foundation Server
26
Microsoft Visual SourceSafe
26
Subversion
26
See Microsoft Visual SourceSafe
Space
replace with underscore
451
Spacing
paragraphs
403
Spell check
language
Standard skins
28
91, 344, 409
Standard toolbar
14
Start Page
53
Startup topic
454
Strict mode
448
Structure bars
- 498 -
362
auto-numbers
366, 373
CHM
449
cross-references
205, 211
fonts
381
FrameMaker
39
HTML Help
449
lists
383
master style sheets
454
mediums
454
next
403
pictures
288, 452
relationship links
248
skins
409
style sheets
333-334, 362, 403, 445
tables
333-334
Word
34, 39
Subversion
26
SVG file
62, 283
SWF file
62, 184-185, 283
Symbols
See Characters
Synchronizing
lists
SourceSafe
Styles
9-10, 403
TOC with open topics
Synonyms
directional
groups
MadCap Feedback
409
303, 307
307
308
303
T
Tables
63, 331
AutoFit behavior
333
auto-numbers
365, 371
captions
333
inserting
331-332
list of
331
relationship
199, 238, 245, 248-251,
260, 453
style sheets
334
styles
333-334
templates
334
Tables of contents
adding
binary
chapters
creating
editing
HTML Help
63, 338, 455
340
410
343
342
343
410
"Tabs" through "Topic IDs"
linking
master
merging
opening
page layouts
page numbers
printed output
projects
proxies
section breaks
skins
targets
338
338, 340, 345, 454
338
341
344
344
455
345
178
344
345
345
Tabs
output window
409
Tags
files
Target frames
Targets
4
85, 196, 207, 213, 219-220,
223
414
adding
417, 433
alias files
122, 448
browse sequences
93, 448
building output
4, 415, 448, 457-461
condition tags
417, 438, 447-448
context-sensitive Help
122
copying
417, 433
destinations
483
editing
417, 448
glossaries
145, 449
master pages
181, 450
master style sheets
454
mediums
454
output types
432
page layouts
451
performance
452
primary
415, 417, 436
publishing
415, 453, 484
relationship tables
260
renaming
417, 435
search filter sets
453
skins
412, 453
tables of contents
345
Target Editor
448
viewing output
415, 468
Task Scheduler
See Windows Task Scheduler
Team Foundation ServerSee Microsoft Team
Foundation Server
Templates
table styles
334
Text
redacted
wraparound
453
288
Text boxes
63, 346, 348
background
borders
floating
headings
padding
positioning
size
wraparound text
350
349
348
382
350
348
348
348
Text Format toolbar
14-15
Text hyperlinks
197
hotspot
inserting
quick
213
213
213
214
Text popups
197
hotspot
inserting
222
222
Text-only popups
See Popups
Thumbnails
pictures
288
TIF file
62, 283, 289, 452
TIFF file
62, 283, 289, 452
TOCs
Togglers
hotspot
inserting
See Tables of contents
197
224
224
Toolbars
global
HTML Help
local
Project
Review
Standard
Text Format
topic
WebHelp
WebHelp Plus
Topic IDs
14
410-411
18
16
17
14
14-15
409
411
411
112
- 499 -
"Topic popups" through "WebHelp AIR"
Topic popups
197
inserting
size
223
223
223
Topic reviews
See Reviews
Topics
4, 61, 64
background image
condition tags
converting to XHTML
creating
cross-references
DOCTYPE
movie links
opening
previewing
printing from CHM
snippet conditions
startup
synchronizing with TOC
287
445
30-32
67
202-203
448
186
72
458
449
323
454
409
Tutorials
Touring the Flare Workspace
Touring the Workspace
9
21
names
system variables
variable sets
352, 354
63, 352
63, 352
352
356
63, 352
VBScript
63, 300
Vector images
62, 283
Version control
See Source control
Videos
See Movies
Viewing
output
primary target output
Visual SourceSafe
455, 468
415
See Microsoft Visual
SourceSafe
Volnum
367
Volumes
auto-numbers
variables
352, 364, 367
63, 352
W
U
W3C
Unbinding
WAV file
78
WAX file
78
drop-down text
expanding text
lists
text hyperlinks
topic popups
Underscores
Unicode
225
226
383, 399
214
223
451
1, 94
UNIX
451
URL
482
User interface
See Workspace
V
Variables
creating
definitions
editing
Heading variables
highlighted
inserting
markers
- 500 -
4, 63, 352
63, 352
357
352, 455
360
63, 352
354
359
353
WCAG
61, 125
126, 207, 213, 292, 298, 448
WDP file
62, 283
Web Content Accessibility Guidelines
Web Layout mode
74
WebHelp
414, 417, 420, 423
accessibility
browser settings
distributing
language
main entry file
Mark of the Web
navigation pane
performance
skin
toolbars
WebHelp AIR
main entry file
See WCAG
448
411
451
471, 474, 476
420-421, 450
472, 474, 477
450
411
452
411
411
420, 423, 455, 471, 476
472, 474, 477
"WebHelp Mobile" through "Yen"
WebHelp Mobile
414, 417, 421, 423, 474,
476
skins
WebHelp Plus
91, 344, 409
304, 414, 417, 422-423,
472, 474, 477
browser settings
distributing
enabling
language
main entry file
Mark of the Web
navigation pane
performance
search
skin
toolbars
411
451
471, 474, 476
455
450
472, 474, 477
450
411
452
304
411
411
Web-safe
images
452
Widows
404
Windows
8, 11
auto-hiding
docking
floating
layouts
moving
21
21
21
22, 148
21
Windows Media
185, 188
Windows Search
422
Windows Task Scheduler
pictures
text boxes
WYSIWYG Editor
288
348
See XML Editor
X
XAML file
62, 283, 456
XHTML
414, 417
file
output
30-32, 64
428, 430
XML
65, 183, 429
file
430
XML Editor
Print Layout mode
Web Layout mode
XPJ file
XPS
xref tag
9
74
74
26
See Microsoft XPS
197, 200
Y
Yen
96
464-465
WM file
78, 185
WMA file
78
WMF file
62, 283, 289, 452
WMV file
185
WMX file
Word
Wraparound text
78, 185
See Microsoft Word
Word Wide Web Consortium
See W3C
Workspace
customizing
main areas
menus
resizing elements
touring the workspace
window layouts
window panes
21
7
14
21
7
22
8, 11, 21
- 501 -
Index
- 502 -

Flare Getting Started Guide

Transcription

Similar documents

AEREON Flare Tip Retrofit Services Marketing Sheet

P9S and VP70Z HK P2Al and Emergency Flare Launcher

Madcap Conv head.indd - MadCap Racing Engines

Fox Racing Shox

Elevated Flares - Prism Integrated Solutions Inc.

AEREON Elevated Flares for the Shale Play Marketing Sheet

laundry room transformation