Tag Editor dialog

The Tag Editor dialog is available from the Authoring menu (main window). This dialog allows you edit Help and Meta tags in HTML files (and other tags and file types if you want).

Introduction | Quick Start
Page: Search | Edit Tags | Insert Tags - Tag Results List

Introduction

The Tag Editor is useful for manipulating single tags <xxxx /> (typically help and meta tags) located in the head section of a HTML file.

Help and Meta tags are usually confined to the <head> section of a HTML file. If required you can search the entire file by editing Settings.INI and adding the following line to the [main] section
FindTagsInBody=Y

Manipulation of non-empty tags eg. <element-name attribute="value">Content</element-name> is not supported. Although the Tag Editor does support the <title>xxx</title> tag (a special case) since help systems normally require this tag.

HTML tags are made up of an element plus one or more attribute/value pairs. Values should be wrapped in quote characters.
eg <element-name attribute="value">

Tags such as Help 2.x Virtual Topic (VTopic) tags are usually located in the body section, and so are not current supported.

Help Friendly Smarts

The Tag Editor specializes in manipulating Help Tags (HTML Help, MS Help 2, MS Help 3) and Meta Tags.

No Duplicates Tags:
When inserting help and meta tags, the Tag Editor will not let you insert the same tag twice. So if you attempt to inserted a duplicate help or meta statement, the insert operation will show no change was made.

No Duplicate Tag Types (Help 2 & Help 3) :
There are certain tag types that should only appear once in a file.
Example: If you insert the Help 2.x tag <MSHelp:TOCTitle Title="Introduction"/> and then repeat with <MSHelp:TOCTitle Title="Different Title"/>, then you will find that the first is removed before the second is added. The MS Help 2.x DTD rules say that the <MSHelp:TOCTitle ...> tag type can only appear once in a file.

MS Help 3 tags that can only appear once in a file:

    <MSHelp:Include File="" />
    <MSHelp:NoSearch />
    <MSHelp:RLTitle Title="" />
    <MSHelp:TOCTitle Title="" />

MS Help 3 tags that can only appear once in a file:

   <title>...</title>
   <meta name="Language" .. />
   <meta name="Microsoft.Help.Id" .. />
   <meta name="Microsoft.Help.Description" .. />
   <meta name="Microsoft.Help.TocParent" .. />
   <meta name="Microsoft.Help.TocOrder" .. />
   <meta name="Microsoft.Help.Product" .. />
   <meta name="Microsoft.Help.ProductVersion" .. />

Smart File Insert Position
The Tag Editor decides where tags should be inserted in the HTML header. If you insert (or rename to) a MS Help 2.x tag you will see the tag is correctly positioned inside a <XML> ... </XML> section. If you rename a Help 2 tag to a Help 3 tag, you will see the tag correctly moved out of the <XML> ... </XML> section.

The Tag Editor will do its best to group similar tags together. FAR treats the Rename operation as a Delete operation, followed by an Insert operation. That way tags are correctly positioned and grouped, and duplicates rules are adhered to.

Quick Start

To begin:

Add the HTML files you wish to work with to the FAR file list (FAR main window).

Open the Tag Editor and select the types of tags you wish to find.

Click "Find Tags" button. The tag list will show all tags found.

The Tag Editor works closely with the FAR file list (main window).
Best to arrange the windows so they lay side by side (or use the "View > Arrange Windows" menu command).

Menus

Most commands listed below are also available in the main menu and in the right+click context menu of the tag result list.

Tag Results List

This control lists all tags found by the Find Tags command.

Columns: Select a column header to sort a column.

Tag Types - displays the tag element-name. eg. <element-name atrib="value">

Count - displays the number of occurrences found of the tag.

Files - displays the number of files containing this tag (a file may contain more than one occurrence of a tag).

Full Tag - displays the full tag text found.

Use Ctrl+Click or Shift+Click to select more than one item in the tag list.

Search page

Find Tags

Find Tags

Click this button to begin searching files (listed in the FAR main window).

Search Dropdown

- Search HTML files only: Only HTML files in the FAR main window will be searched.
- Search Selected files only: Only files that are selected in the FAR main window will be searched.
- Search All files: All files will be searched.

Sort tag list after filling

Normally tags results are arranged in the order that they were found. This setting tells FAR to automatically sort the list whenever a search is performed.

Search options

Find HTML Help Tags

Check this to find HTML Help meta tags. The only tags used by HTML Help are the following KLink and ALink.
<META NAME="MS-HKWD" CONTENT="keywords">
<META NAME="MS-HAID" CONTENT="keywords">
These embedded index tags are not widely used outside Microsoft. Most users define keywords in a .HHK file.

Find Help 2.x Tags

Check this to find MS Help 2 tags. MS Help 2 is used by Visual Studio 7.x, 8.x and 9.x help.
Help 2 tags need to be wrapped in a <XML> tags (the Tag Editor does this for you).
Examples of Help 2 tags:
<XML>
    <MSHelp:TOCTitle Title="H2Reg Command-line"/>
    <MSHelp:RLTitle Title="H2Reg Command-line"/>
    <MSHelp:Keyword Index="F" Term="VS.Ambient"/>
    <MSHelp:Attr Name="Information Type" Value="Orientation"/>
</XML>

Find Help 3.x Tags

Every document must have a minimum of a <title>my title</title>
and a unique asset ID (typically a GUID since it must be globally unique)
eg. <meta name=”Microsoft.Help.Id” content=”MyTopicIdentifier” />
See a full description of help 3 tags at http://kb.helpwaregroup.com/ms-help-viewer

Find Meta Tags

Check this to find all Meta tags. Meta tags are typically in the form:
<meta name="name-value" content="content-value">

Find <title>...</title>

Title a special case where we do allow non-empty tag. Check this to find all document title tags. Most help system require a title. In Help 3 it is mandatory.

Find Tag elements starting with

Use this to find other tag elements not listed above.
EG. Enter "!--" in the associated entry field to find comment fields 
Enter nothing in the associated entry field to find all tags.

Must Contain text

Enter search constraints into one or both boxes. During a search, only tags containing the search constraint text will be displayed. Leave boxes empty to do nothing.

Must Not Contain

Enter search constraints into one or both boxes. During a search only tags NOT containing the search constraint text will be displayed. Leave boxes empty to do nothing.

Select

Select FAR Files containing Selected Tags

First select one or more tags in the Tag result list. Click this button to highlight all FAR files (main window) that contain the selected tags. Alternatively you can double click a tag result list item.

Select Tags found in Selected FAR Files

First select one or more files (FAR main window). Click this button to highlight all tags (tag result list) that are contained in the selected files.

Ctrl+Left, Ctrl+Right are short cuts for these commands. Note that Ctrl+Right can also be used in file list of the FAR main window as well.

Group after selection

When this control is checked the resultant selections (of the select commands above) are grouped together at the top of the list.

Edit Tags page

Delete Selected Tags

Select one or more tags from the tag result list and click the Delete button. All selected tags will be deleted from the associated files.

If the "Selected Files Only" checkbox is checked then only selected files (main window file list) will be edited.

To see which files were actually modified, look at the File list Replacements/Matches columns (main window).

Deleted tag(s) will remain in the list (with a zero count) until you refresh the list using "Find Tags" button.

Rename Selected Tags

Select the tags you want to rename (from the Tag list). You can optionally select a tag template from the end of the drop down list. Finally enter the changes you want and click the Rename button.

The rename drop down contains predefined templates at the end of the dropdown list. The top of the list contains edits you have recently used.

The rename operation is performed in 2 steps: A Delete, then an Insert. After a rename operation, deleted tags will have their counts decremented, and newly inserted tags will appear at the end of the tag list. If the new items were already in the list, then those items will be selected and have their file counts updated.

Selected Files Only: check to rename selected files only (main window file list) instead of all files.

Insert Only (no Delete): check to insert the new tag without deleting the selected tag.

After renaming you can refresh the list by using the "Find Tag" button.

Template Example 1:

<%Element% %A1%="%V1%" %A2%="%V2%">

If we edited this to be <%Element% xxx="%V1%" yyy="%V2%">
then the first attribute would be set to xxx and the second attribute would be set to yyy for all selected tags.

Template Example 2:

<META name="%name%" content="%content%">

Very useful if your name= and content= attributes are in the wrong order.
%name% is always the value associated with each name= attribute.
%content% is always the value associated with each content= attribute.

Also %fred% would store the value for attribute fred= and so on.

Getting the idea? Experiment with it.
Here are the available place holders recognized by the replace command.

%Element% - Contains the current tag element.

%A1% - contains the first tag attribute.

%V1% - contains the first tag attribute value.

%A2% - contains the second tag attribute.

%V2% - contains the second tag attribute value.

%xxx% - contains the value of the xxx=value data pair. Here xxx could be any text.

%title% - contains the title of the HTML -- I.E. <title>This Bit</title>

%guid% - generates a unique GUID string identifier.

%filename% - replaced by the current filename, no directory.

%filenameNoext% - replaced by the current filename, no directory, no file extension.

Note: GUIDs are 128 bit numbers. The probability that a GUID you generate will be absolutely unique (for the entire world) is extremely high.

Insert Tags page

Enter one or more tags into the multiline entry field (one tag per line).

Select the files you want to update (FAR main window). The tag list is ignored by this command.

Click the Insert button. Your tags will be inserted, one by one, into each of the selected files.

The Tag Result list background is blue-gray on this page indicating that it is not used by the Insert command.

Once the insert operation is complete, the inserted Tag(s) will appear highlighted in the tag list.

The dropdown list (button on the right side) provides a list of all common help tags. Refer to Microsoft MSDN reference pages for assistance on formatting help tags.

Available place holders:

%title% - This is replaced by the title of the HTML -- IE. <title>This Bit</title>

%guid% - Generates a unique GUID string identifier.

%filename% - replaced by the current filename, no directory.

%filenameNoext% - replaced by the current filename, no directory, no file extension.

http://www.HelpwareGroup.com/