Tech Write Tips

January 11, 2007

What Is (Are): Regular Expressions

Filed under: Madcap Flare,Technology,Tip,Tool,What is — AndyR @ 1:15 pm

regexp.gifRegular 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.
Advertisements

November 22, 2006

Flare 9 – XML Editor 2

Filed under: Madcap Flare,Tool — AndyR @ 1:05 am

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.

xmledit_continuelist.gifContinue 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.

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

xmledit_insert.gifInsert 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.

xmlanchor.gifAnchor
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!

October 16, 2006

Flare 7: File List

Filed under: Information Types,Madcap Flare,Technology,Tip,Tool — AndyR @ 12:09 pm

filelist.gifFlare 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.

August 16, 2006

Flare 5: Adding Advanced HTMLHelp Features

Filed under: HTMLHelp,Madcap Flare,Tip,Tool — AndyR @ 12:38 pm

htmlhelpworkshop1.gifIn 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.

August 3, 2006

Best Pratice: Flare 4 – High Definition PDF Part 3

Filed under: Madcap Flare,Technology,Tool — AndyR @ 12:47 pm

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.

July 12, 2006

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

Filed under: Madcap Flare,Tip,Tool — AndyR @ 12:35 pm

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.

flare_layout.gifPictured 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

Filed under: Tip,Tool — AndyR @ 6:55 am

replace.gifSo 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.

July 6, 2006

Best Pratice: Flare 1 – Reporting

Filed under: Best Practice,Madcap Flare,Tool — AndyR @ 12:32 pm

The first of our mini-series of tips for Flare, here we consider how to leverage that old RoboHelp licence to squeeze some extra information out on your Flare HTMLHelps. 

It is advisable to ensure the following checks towards the end of a help project:

  1. Technical correctness check by Designer
  2. Help integrity checks by Technical Author
  3. Grammatical check by Proof Reader
  4. Accessibility check by the Tester
     

The second stage here requires a high degree of reporting information. To aid us with this we need to leverage functionality in RoboHelp until the reporting in Flare is updated. The following process enables you to gain a whole host of additional information about your Flare HTMLHelp project. Perhaps you CAN have your cake and eat it:

  1. Towards the end of your help project in flare.
  2. Generate output and save a log of the issue as a report.
  3. Run through this report, correcting the errors.
  4. Generate output again.
  5. Take a copy of the temporary output from:
    1. PROJECT\Output\USER\Temporary\Microsoft HTML Help\Content.
  6. Open the _Temp.hhp in your legacy copy of RoboHelp.
  7. Work through the topics in the RoboHelp Broken links section to fix links back in flare.
  8. Select the TOC in Robohelp, check through the list for topics not included in the TOC. Add these items into the TOC back in Flare as appropriate.
  9. Select Tools | Report in RoboHelp and use any additional reports to check content.

February 17, 2006

What is: CSS

Filed under: Technology,Tool,What is — AndyR @ 1:26 pm

Originally HTML webpages combined both content and appearance. For example you had to embed a <Font/> tag in amoungst your content to specify a font. CSS enables you to control the look and feel of webpages without interfering with the content. Becuase of it’s exclusively appearance focus it uses a different syntax to that originally used in HTML.

The advantage of this separation is that you read the appearance syntax alot easier as it is not mixed up with the content. The same is true of the content, being free of appearance tags. You can also use one CSS to control the appearance of multiple wepages, which makes it easier if you need to alter their appearance.

When starting to work with CSS it is essential to work with a tool that can help you with the syntax. Topstyle Lite is a free tool that enables you to pick the styles from a list rather than type them in. Flare is a more comprehensive tool that integrates CSS not only with a WYSIWYG HTML editor, but also manages all other aspects of producing online help.

As you familiarise yourself with CSS, which for me has been a good 5 year journey, you will gain an increasing understanding of how best to use it. The learning curev usually develops along the following: Syntax Familiarisation; Relating Styles to Particular HTML Tags; Higherarchey of Formatting; Conditional Styles.

Create a free website or blog at WordPress.com.