Flare 9 – XML Editor 2

In this post we dig a little deeper into Flare’s neat XML Editor. If you’ve not read the previous post on this it would probably be a good idea to swing by and read that first.

First we should highlight that these icons are only available when you are in non-tag editing mode. It appears that this is the mode that Madcap expect us to use for the majority of editing. It seems to get more attention for bug fixes and enhancements than the tag view. And when you are used to it, it is very quick and flexible.

Continue List
This icon appears when you have pressed return at the end of a nested ordered list. If you click the icon it will continue the parent list, if you don’t you insert paragraphs.

Image Resize
This icon appears on inserted images and enables you to manually resize the image, maintaining its aspect.

Insert Pointers
These two place holders appear when you are dragging an item onto a topic from the Content Explorer, File list or TOC. It is useful to understand the two pointers as they enable you to both located where you were working before you dragged the item, and accurately place the item you are dragging.

Anchor
This appears if you hover over an anchor tag. It displays the location of the link. If it is blank, the linked topic could not be found, or was not valid XHTML.

So there we have it, a few more tit-bits for you guys. Let  me know if you’ve spotted any other useful behaviour!

Flare 8 – XML Editor

Now that I’m getting more at home with Flare’s XML editor, and things are holding together better, and performing a lot faster, I thought it would be useful to give a run down of some the of intricacies.

The following are useful in the non-tag view:

Red control box: Appears when you highlight a section of text. Hover to expand, then left click to access the quick copy and paste menu.

Yellow control box: Appears at the start of a tag section. Hover to expand, then left click to access the advanced tag editing menu.

Tag Start: Cursor signifies the start of a xhtml tag.

Tag Middle: Cursor signifies you are within an xhtml tag and can edit the contents.

Tag End: Cursor signifies the end of a xhtml tag.

 

Tag Between: Cursor signifies you are between tags. Type to enter text into the parent tag.

 

Tag Before – Level 1: Cursor size signifies you are in the first of a series of nested tags.

Tag Before – Level 2: Cursor size signifies you are in the second of a series of nested tags.

 

Tag Before – Level 3: Cursor size signifies you are in the third of a series of nested tags.

There we have it. Hopefully these details will de-mysitfy this great little editor. I just need to talk mouse pointers now.

Flare 7: File List

Flare 2.0 further substantiates the breeding we have come to expect from the Madcap stable. This version introduces new features and beefs up performance. This is the first of a few posts that will focus on different features of Flare 2.0.

Today we address the new File List pane, available by selecting View | File List from the menu. As with all components of the Flare interface, this can be positioned to provide easy access as is appropriate to your working style.

The File List pane enables you to view all the files in your project in one list. This list can then be ordered and filtered as required. at first this doesn’t seem all that significant, but when combined with other components of Flare’s flexible interface it enables a number of productivity enhancements.

• Image Pallet: By filtering the list to include images (*.gif; *.jpg) you can use the list as a source of images for your topics. Rather than having to browse to the required image you can simple drag-and-drop the image from the File List to the topic. Ensure you drag the image icon rather the the text.
• Edited Files Pallet: By filtering the list to include html files (*.htm; *.html) and ordering by Date Modified you can use this as an unlimited recently list list. This complements the File | Recent Files menu, as it provides a longer list and potentially quicker access to the files.
• StyleSheet Management: By filtering the list to include html files (*.htm;*.html) you can view the style sheet in use by each topic. Order the list by Style sheet to group the different style sheets together. This enables you to weed out old style sheets and ensure all topics are on the latest version of your style control.
• Condition Management: By multi-selecting a collection (hold CTRL) or range (hold SHIFT) of topics, right-clicking and selecting Properties from the pop-up menu, you can specify Basic, Topic, Conditional and Language properties on multiple topics. This is particularly useful when managing conditional topics. You can also use the list, ordered by conditions, to further assist the management of conditional topics.
• Topic Type Editing: By filtering the list by a particular file name you can edit a certain type of topics. (Assuming you have consistently named your topic files) This enables you to rename and edit these topics to ensure they are consistent. For example, filter by ‘*about.*’ to work with all the about topics.

All-in-all the File List pane provides some excellent additional ways of working. Once it includes the ability to view which topics are in the TOC and Index, and filter by folders it will become a key way of working with Flare 2.0.

Flare 6: Customise Your Environment

As mentioned previously , now that many of us have been using Flare for some time, we have spent considerable time diggin around and ticking out our Flare workspace to best fit our working practice.

I thought it might be useful to share these layouts with each other, and give an overview of what you can achieve. To that end, the following layouts have prooved popular:

Compact: Uses the minimal space to provide the maximum information about the help. You can see the Content, TOC and edit two topoics symaltaneously.

–

Multi-tasker: Provides a good varied coverage of information. The full height Content and TOC enable you to view a larger portion of these treeviews. It also retains access to the Start Page to enable quick access to your projects.

–

Minimalist: This provides the minimum of clutter in the interface, just the Content and one Topic. If you know your hotkeys well this can be further minimalised by turning off unwanted toolbars.

–

Sandwich: This provides the topic in the middle, sandwiched between the Content and TOC panes. This enables a quite view of all key information, whilst keeping the focus on the content being edited.

–

Dual Monitor: This enables you to have one topic on the right monitor providing additional space on the original screen. 

–

–

Multiple Progects: This enables you to quickly switch between different projects via the open project pane that has been “floated” off to the right. In my setup I combine this with a dual screen system to good affect.

–

Let me know how you have yours layed out and I’ll add it to the list.

Flare 5: Adding Advanced HTMLHelp Features

In this post, we return to some more nuts and bolts issues regarding Flare and HTMLHelp.

Flare current provides the majority of HTMLHelp settings, and does this in a much more flexible way that HTMLHelp workshop does. Particularly useful are the WYSIWYG help window size and potitioning.

However, there are some advanced HTMLHelp settings (such as advanced help, or remembering the users last help settings) that are not currently available. Until these make it into the software you can still access these features by employing HTMLHelp workshop (which can be downloaded free from microsoft).

1. Once you have finalised your help project.
2. Generate the HTMLHELP output.
   Open the PROJECT\Output\USER\Temporary\Microsoft HTML Help\Content\_Temp.hhp in HTMLHelp Workshop.
3. Click the Add/Modify Window Definitions button.
4. Use the Window types dialog to make your advanced settings.
   1. The Navigation tab enables you to specify the Advanced search.
   2. The Positoin tab enables you to specify to save the users window position for help.
5. Click OK to save the changes.
6. Generate the help in HTMLHelp Workshop.
7. You can then access your enhanced HTMLHelp .chm in the PROJECT\Output\USER\Temporary\Microsoft HTML Help\Content folder.

Best Pratice: Flare 4 – High Definition PDF Part 3

Having sketched out an approach that enables you to produce a high qualifty fully featured PDF document from your Flare content, we will now look at some of the technical hurdles to establishing this technique.

XSL Issues : Access each of the files in the Flare TOC

You need to pass you flare toc into the XSL then use that to call each XHTML file referenced in the Flare TOC to then output the required content.

    <xsl:for-each select=”TocEntry”>
      <xsl:for-each select=”document(@Link)//BODY”>
       <fo:block color=”#2A2A2A” font-size=”10pt” font-weight=”normal” space-before=”6pt”>
        <xsl:apply-templates/>
       </fo:block>
      </xsl:for-each>

XHTML Issues: Convert content from XHTML to XML FO

Your template needs to handle each of the XHTML tags you are using in your topics and convert them to an XML FO syntax. For example <P> tags can be converted as follows: 

<xsl:template match=”p|P”>
  <fo:block keep-with-next=”always” text-align=”justify” color=”#2A2A2A” font-size=”10pt” font-weight=”normal” space-before=”6pt”>
   <xsl:apply-templates/>
  </fo:block>
 </xsl:template>

XSL Issue: Identify the location of Images

Your XSL template needs to take the relative SRC attribute for <IMG> tags and work out the actual location of the image file implied by this value. A template can be constructed in XSL to calculate the location.

XSL Issue: Cross Referencing from Anchor tags

Your XSL template needs to calculate the abolosute location referred to by each <A> tag. This can be achieved by using the current location in the TOC Flare that the XSL is passing, and the HREF attribute of the <A> to construct the absolute position.

This position can then be used as a unique id for XML FO cross reference (where $current is the calculated value of this absolute reference):

<fo:inline margin-left=”-10mm”>
  <fo:basic-link margin-left=”-20mm” text-decoration=”underline” internal-destination=”{translate($current,’/\.:-_’,”)}”>
      <xsl:apply-templates>
      <xsl:with-param name=”l” select=”$l”/></xsl:apply-templates> 
  </fo:basic-link>
</fo:inline>
<fo:inline text-decoration=”none” space-end=”-2.5mm” font-size=”7pt”>
      (see page <fo:page-number-citation text-align=”right” ref-id=”{translate($current,’ /\.:-_’,”)}”/>)
</fo:inline> 

We will be adding to this and expanding on examples as the discussion develops in the comments.

Best Pratice: Flare 4 – High Definition PDF Part 2

Having introduced the concept of high definition PDF’s output straight from Flare’s source files with minimal post-production, we can now start to dig into the technologies that are used to produce it.

The XSL style sheet produces the following sections of XML-FO :

• Page Layout Definitions
  • Page Sizes and Layout
  • Branded Headers and Footers
  • Odd Even Pages
• Branded Title Pages
• It firstly calls the Flare TOC file, using the @Title element, to create the bookmarks for the pdf.
• It secondly calls the Flare TOC file, using the @Title element to create a structure for the document.
  • Table of Contents
  • Chapters
  • Main Headings
• It thirdly calls the Flare TOC file, using the @Link element to locate each topic in turn.
  • Each topic is then added to the above structure.
• Branded Back Pages 

This is all wrapped up as one big XML-FO file.

The XML-FO file is then passed into the Apache FOP engine which outputs the PDF document.

In the next part we’ll look at some of the key issues to solve with this process and the code you can use to overcome them.

Best Pratice: Flare 4 – High Definition PDF Part 1

In this article we take things up a notch. This enters the realm of the real tech tip. If you want your authoring tool to do everything for you and don’t want to delve into CSS, XML and XSL then maybe you should move onto the next post.

Those still reading, lets roll our sleves up and have a look under the hood. The aim of todays article to to produce a high quality pdf document that has at least the following features:

• Front Matter
  • Graphical Front and Back page
  • Table of Contents for the book
• Separate Chapters
  • Mini Table of Contents for each Chapter
  • Chapter name in the header
  • Clickable links from Table of Contents to relevant section
  • Marginalia (notes, references, notifiers)
• Full Bookmark tree.
• Odd/Even Pages
• Odd/Even Headers and Footers

Bit of a tall order, maybe. But with the following technology you can achieve this from your Flare source files. Once setup you can then generate it at the click of a button.

The technology we will be using are XML, XSL, XPATH and XML-FO. In part 2 we will detail the steps in this process.

Flare 3: Custom Layout – How do you use yours?

This is the third in a series of post about how to get the most out of Madcap Flare. We’ve look at Reporting and  Topic Titles, now a little post about the flexible user configurable layout.

Pictured on the right, using a screen portrait of course, is my current setup for producing help with Flare. After experimenting with a few different models, this seem to be the most productive for me. It is achieved as follows:

1. Open Flare.
2. Open a project.
3. Click the Primary tab title to select it.
4. Select Window | Floating, to float the Primary toc.
5. Drag the Primary Toc over the left pane, likely to be the content explorer.
6. Drop it on the the right arrow which appears to tile it on the right.
7. Ensure Document Dock is on via the Window menu.
8. Open a topic, which will open in the document dock.
9. Drag the document dock to the right and drop it onto the left arrow that appears over the start page so the at tiles to the left.

You can now view the Content Explorer (for direct access to the files), the Primary TOC to manage the help and edit in the Document Dock.

Additionally you can sent topics to the far right pane by pressing shift control-D.

Let me know if you agree, but for me this is a very productive workspace which minimises both navigation and page sawpping.

Best Practice: Flare 2 – Automated Themed Topic Types

As we suggested in our previous topic types post, to ensure you are ready for future help formats it is advisable that your topics provide information in clearly defeind types. This post considers how you can present these topics in an HTMLHelp in such a way that it is clear what sort of information is being communication.

Topic Titles
The first step in this task is to ensure that you have consistently named your topics, as we discussed in our delicious topic title post. You need to define a set of rules that specifies how you name your topics and then stick to it.

One rule could be to always title concept topics ‘Concepts:…’. Another might be to always include the control type in your software screen focused topics, for example ‘Select Window’, ‘Open Frame’ or ‘Close Tool’.

Dynamic Header
The next step is to include a .js file in your Flare project to output content at the top of your topic. It is advisable for this to be directly after the <Body> tag, and referenced as follows:

<script language=”JavaScript1.2″ type=”text/javascript” src=”Head.js” mce_src=”Head.js”></script>

Detect Topic Type
This head.js javascript then need to interrogate the title of the html file, (document.title) then check it:

1. If it contains concepts, then output a concept header.
2. If it contains Window, Frame etc, then output a software control header.
3. Otherwise output a procedural header.

The content of the header will need to be output with the following javascript:

document.write(‘<H1 class=”topic_type1″>’+document.title + ‘</H1>’)

In this example we are using the heading one class to apply the format, which is controlled in our .css file in flare. This can make use of colours and icons to make it clear what sort of information is being provided.

The beauty of this approach is that should you need to change the criteria or the look and feel of each topic, you simply update your one .js file.