What Is (Are): Regular Expressions

Regular expressions are used to perform complex searches in software such as Flare and Textpad. They enable you to identify phrases that are not (“a^b”) followed by particular characters. They enable you identify phrases that can contain optional (“a|b”) sections.

Some examples of these phrases, used in practice by technical authors are as follows:

• “[^=|(]”[^ |>|?|/|)]” – Find quotes not in HTML attributes. We only use single quotes. This expression locates any quotes not related to an HTML attribute, i.e. in the body of the topic text.
  • Avoids ‘” ‘ (end of attribute mid tag)
  • Avoids ‘”/>’ (end of attribute end tag)
  • Avoids ‘=”‘ (start of arrtibute)
  • Avoids ‘”?’ (header doctype)
  • Avoids ‘(“‘ (filename in quotes)
• “[^,]” – Find the phrase without a preceeding comma. This is useful if you always use phrases of the form “To achieve XXX, perform the following”. It identifes any places you have missed the “,”.
• “[^(his)|(he)|(current)] dialog[^<|s| |)]” – This assumes you provide links from procedural topics to screen topics. For example from “Student Dialog”. It works by identifying all occurences of “dialog” that are not proceeded with the end of the link “</a>”.
  • Avoids “This dialog”
  • Avoids “The dialog”
  • Avoids “Current dialog”
  • Avoids “dialogs”
  • Avoids “dialog “
  • Avoids “dialog)”
  • Finds “dialogs” not followed by “</a>”
• “tab[^<|s| |e|a|l|]” – This assumes you provide links from procedural topics to screen topics. For example from “Student tab”. It works by identifying all occurences of “tab” that are not proceeded with the end of the link “</a>”.
  • Avoids “tabs”
  • Avoids “tab “
  • Avoids “tabe”
  • Avoids “taba”
  • Avoids “tabl” (table)
• “[^(and)|(This)|(</a>)] Tab[^h|<|\.|”|l|e|s|a]” – We always have the control type (dialog, tab etc) in lowercase, this expression identifies any cases where “Tab” is uppercase and not the start of a sentance. It also rules out occurences inside “Table” etc.
• “<img.*/> “– Images with spaces afterwards. We insert spaces after images via a css style, so need to ensure that the images don’t have “hard spaces” after them.
• “[^ |>]<a” – Find links without whitespace before them.
• “[^ |>|(]<b>” – Find bold text without whitespace after.
• “<a.[^(href)]” – links with no href tag.
• “href=””” – links with empty hrefs.

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.

What is: XAML (authoring’s best kept secret)

XAML is an XML file that defines user interfaces. It not only defines the frames, buttons, fields but also introduces any other visual effect that the interface may require. In a similar way to Flash interfaces, XAML provides a rich user experience with a variety of graphical effects.

XAML, a markup language to declaratively represent user interface for Windows applications, improving the richness of the tools with which developers and designers can compose and repurpose UI.

For example, you could define a button as follows:
<Button>
  <Button.Background>
    <SolidColorBrush Color=”Blue”/>
  </Button.Background>
  <Button.Foreground>
    <SolidColorBrush Color=”Red”/>
  </Button.Foreground>
  This is a button
</Button>

So what! How does this help the technical author? Here we find one of the best kept secrets of this new technology. Whilst its benefits for programmers and designers is often highlighted:

“One great benefit of XAML is that it helps to separate design and development, which actually helps to improve collaboration and efficiency between designers and software developers.”

What is less publicised is how this opens up the development process to other players, such as the technical author. Not only does this help close the great divide between authors and devlopers, it also starts to provide a route to achieving the sort of user guidance offered by Assistance Platform.

Firstly, it becomes a possibility for the technical author to become the owner of all the text in the appication. The user interface text in the XAML files can easily be updated with little programming knowledge.

Sceondly, it also become possible to generate templates for dialog help, as the XAML can be transformed with an XSL to produce a XHTML page that lists all the fields and includes notes as the starting point of the help project.

Thirdly, the XAML itself can also be checked from a consistency perspective. An XSL file can run through the file checking it aganist the companies interface standards. Again this helps the technical author flag up any issues with the user interface.

We find that this helps, authors move towards providing more wide spread User Assistance than simple help files. Aspects of Vista, such as super tooltips, require much more integration between the help content and the application. XAML provides a means for us, technical authors, to play our part to achieve this.

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.

Best Practice: Screen Estate

As mentioned in the Jenson Blog recently, screen real-estate is at an all time premium. When you see how much time and effort is spent ensuring software doesn’t needlessly waste screen real-estate, it makes you realise the responsibility we have as authors to use the help window wisely.

Alot of benefit can be gained by considering ways in which we can make best use of the space.

• Provide navigation within each topic so the users doesn’t have to open the TOC to move around the help.
  • Breadcrumb trail
  • Cross Topic links
  • See Also links
• Open the HTMLHelp with TOC minimised
• Desgin topics to fit in smaller portion of screen.
  • Screen shots width is critical
  • Tables used for content or layout should fit width
• Avoid scroll bars appearing by fitting content to one window
  • Turn off test on the HTMLHelp toolbar buttons
  • Provide help topic in a pane contained in the application.
  • Turn off keep help on top.

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.

We’re back…

Hello again.

I’ll have a new post for you later this week. In the meantime, how about having a dig into some of the pdf generation ideas we are discussing.

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.

Create Table from Tabbed Text

So you have copied a table out of Word or some other package and paste it into your Topic or html. This comes in as tab separated rows, one row on each line. Now you want to recreate the table, but this will invovle laborious cutting and pasting right?

Not necessarily, the following procedure enables you to create the table using a simple series of search and replace commands:

1. You can use a program such as textpad (or any text editor) to performa the search and replace.
2. Replace the tab character with </td><td>.
3. Replace the line break character “/n” with “</td></tr>/n<tr><td>”
4. Then all you need to do is wrap the table with <table> tags and a little cleaning up.

This has saved me countless hours of content adjustment. Let me know how you get on, in the comments.