Command Line Compiles
Previous Topic  Next Topic 

There are two ways of controlling Fast-Help from the Command Line. The first is through passing simple commands, such as which Project to open and whether to compile to a specific format. This is available in all versions of Fast-Help. The second way is to pass an ini file, containing advanced commands. This way is available only in the Corporate Edition.


Simple Command Line Compiles

Fast-Help takes 3 parameters from the command line, the first is the Project name, the second is an optional compile command and the third is an optional request to keep Fast-Help open.


1st Parameter: Project Name - Type in the full path to the project, i.e:

  FastHelp.exe "C:\Test\My Project.mdb"


2nd Parameter: Compile option - This is optional. Type in the parameter "-compile=" followed by the format to compile, examples are:


FastHelp.exe "C:\Test\My Project.mdb" -compile=HtmlHelp

FastHelp.exe "C:\Test\My Project.mdb" -compile=WinHelp

FastHelp.exe "C:\Test\My Project.mdb" -compile=RTF

FastHelp.exe "C:\Test\My Project.mdb" -compile=Printable

FastHelp.exe "C:\Test\My Project.mdb" -compile=PDF

FastHelp.exe "C:\Test\My Project.mdb" -compile=PocketPC

FastHelp.exe "C:\Test\My Project.mdb" -compile=WebSite

FastHelp.exe "C:\Test\My Project.mdb" -compile=wxWidgets


3rd Parameter: -StayOpen - this is optional and if omitted then FastHelp will close after compiling. It this is included FastHelp will remain open. i.e.


FastHelp.exe "C:\Test\My Project.mdb" -compile=HtmlHelp -StayOpen


Advanced Command Line Compiles Using ini files

Please note this option is available only in the Corporate Edition. In the Templates folder you will find a file called "Command Line Compiles.ini". You can use this as the basis for your own command line compiles. For example, if you want to compile a Project called "Acme Products.mdb", for two different customers, you could save the ini file as "For Microsoft.ini" and "For All Others.ini". You can save the ini files wherever you like, but it is probably best to save them into the same folder as your Project. For example, if you saved your ini files into your Project folder, which was "C:\My Projects\Acme Products 2006", your command line would look like this:

  "C:\Program Files\FastHelp\FastHelp.exe" "C:\My Projects\Acme Products 2006\For All Others.ini"

Fast-Help will then load and read in the ini file and process all the commands within it. The most basic command tells Fast-Help the name of your Project to load. Below you can see that the first section in the ini file is the [Project] section. The command "ProjectFileName" specifies the Project. This needs to be a full path, as per the screenshot below.

If you were to just pass this ini file to Fast-Help, your Project would be loaded and then Fast-Help would close. So effectively it would not do anything useful, so we need to tell it what format to compile to. This brings us to the next important section, the [Compile Options], which contains the following two important commands:

  CloseAfterCompile=Y

  FormatToCompileTo=htmlhelp

The CloseAfterCompile command is either "Y" or "N". If you do not specify it, Fast-Help will simply close after compiling. To force Fast-Help to stay open, set this command to "N". The FormatToCompileTo command takes the following options:

  winhelp

  htmlhelp

  website

  rtf

  pdf

  pocketpc

  wxwidgets

So, if you have an ini file like the screenshot below:

It will load your Project and compile it to HtmlHelp and then close.


Multiple Compiles

You can compile to more than one format in the same ini file. For example, you may want to compile to HtmlHelp and PDF using the same options. The following options allow you to compile a up to 7 different compile formats:

  SecondCompile=pdf

  ThirdCompile=pocketpc

  FourthCompile=rtf

  FifthCompile=wxwidgets

  SixthCompile=website

  SeventhCompile=winhelp

You only need to specify the options that you need for the current ini file. For example, to compile to HtmlHelp and PDF, your [Compile Options] would look like this:

  [Compile Options]

  FormatToCompileTo=htmlhelp

  SecondCompile=pdf

Each compile will complete in the sequence it is listed, up to the SeventhCompile option.


Setting Variables

Let's say that we have two Variables called "Company Name" and "Copyright". If we are compiling using our "For All Others.ini" file, we may want to set these variables to different values than we perhaps would want for the "For Microsoft.ini" file. To set the variables, we use the [Variables] section. Type the variable name, without the square brackets and leading $ sign. Then add the equals sign, and the text to replace the variable with, as per the screenshot below:

Please note that setting variables in this way will set the variable to "Plain Text only", i.e, the variable will take on the formatting of the surrounding help text.


I am sure you can see how powerful this can be - you can have many ini files with groups of variables customized for specific customers or users.


Setting Conditions

Let's say you have two Conditions called "NOT YET LIVE" and "For Microsoft Only". In the [Conditions] section you simply type the Condition name followed by the equals sign and either a "Y" for include or a "N" to exclude. See the screenshot below for an example:


Excluding Topics or Popups

There may be occasions where you want to exclude topic or popup pages that are specific to a Customer. There are two sections to handle this, [ExcludeTopics] and [ExcludePopups]. These sections require the use of the ContextString of the page to identify it. For example, if you have a page with a Title of "Welcome to Acme v1.0", if you click on the Properties tab you will see a ContextString that looks like "WelcomeToAcmeV10". The ContextString is a unique identifier for the page. In the screenshot below, the topic "WelcomeToAcmeV10" will be excluded from the next compile, and the topic "Introduction" will be included. Also, the popup "WhatIsAFilter" will be included.


Translations

There are two options that affect Translations, the LanguageToLoad and whether you are compiling a translation or not. This section looks like this below:

  [Translations]

  LanguageToLoad=Korean

  CompileTranslation=Y

In this case above we are loading an existing translation, "Korean", and we will be compiling the translation, because it is set to "Y".


HtmlHelp Specific Options

From the ini file, you can set all the same options that you can on the interactive Compile screen. None of these options are required. They simply allow you to change the settings that you see on the compile screen. If you do not want to make any changes to the settings you see when you are using Fast-Help interactively, then you can omit all the following sections.


One handy option below is to specify a different file name to compile to. In the example screenshot below the FileName is set to Acme General. Note that the CHM file extension is not used. This will be added automatically by Fast-Help.

You can also specify a destination for the compiled CHM file to be copied to, using the "CopyFileTo" option. The rest of the options in all the sections below are the same ones that you see on the compile screen. Setting them equal to "Y" is the same as checking an option, and un-checking an option is equivalent to setting it to "N".

[HtmlHelp Options]

FileName

The compiled file name without an extension.

IncludeNonscroll

When set to "Y", the nonscroll region, which is the header section above the main help text, will be included.

AddBrowseButtons

When set to "Y", navigation buttons will be added to the Nonscroll area.

ConvertUnicodeToAnsi

When set to "Y", any unicode text will be converted to ansi using the current locale settings from Windows control panel.

UseInternationalCharacterSet

If the ConvertUnicodeToAnsi is set to "Y" then when this option is set to "Y", the conversion will use the locale settings from the "International Options" in HtmlHelp Compiler Options, rather than the Windows control panel.

AutomaticallySortTheIndex

This will sort all the keywords on the Index tab in alphabetic order.

QuickCompile

When set to "Y", only those pages which have changed since the last compile will be re-processed, speeding up the compile process. Setting this to "N" will force all pages to be refreshed.

ConvertBMPsToJPGs

Although HtmlHelp will display bitmaps, they are usually large in size. Setting this option to "Y" will convert them to compressed JPGs, decreasing the size of the chm file.

AutoLink

When set to "Y", the AutoLinking feature will process each page and automatically add links to key phrases and words.

CopyFileTo

Copies the compiled .chm file to this folder.



WinHelp Specific Options

[WinHelp Options]

FileName

The compiled file name without an extension.

Compress

When set to "Y", the compiler will try to compress the .hlp file. This will mostly work well when your project uses a lot of images. Sometimes the compress fails, as the Microsoft compiler is a little temperamental.

AutomaticBrowseSequence

When set to "Y", navigation buttons will be added to the Nonscroll area.

AutomaticallySortTheIndex

This will sort all the keywords on the Index tab in alphabetic order.

CopyFileTo

Copies the compiled .hlp and .cnt files to this folder.



Website Specific Options

[Website Options]

HomePageFileName

The home page, usually "index", without an extension.

IncludeContents

When set to "Y", the Contents tab will be included.

IncludeIndex

When set to "Y", the Index tab will be included.

IncludeSearch

When set to "Y", the Search tab will be included.

FullTextSearch

Normally, search phrases are limited to keywords and titles, but when this option is set to "Y", all text in your website will be included. This takes up more memory but can be very useful.

IncludeNonscroll

When set to "Y", the nonscroll region, which is the header section above the main help text, will be included.

AddBrowseButtons

When set to "Y", navigation buttons will be added to the Nonscroll area.

QuickCompile

When set to "Y", only those pages which have changed since the last compile will be re-processed, speeding up the compile process. Setting this to "N" will force all pages to be refreshed.

AllowAccessToThisSiteViaSSL

The website normally has a reference to "about:blank" inserted in it, but SSL sites complain about this, so when this option is set to "Y", this reference is omitted.

EnableAppleMacBrowserSupport

The Safari browser does not work with unicode JavaScript files, so when this option is checked the JavaScript files are saved in ansi mode.

AutoLink

When set to "Y", the AutoLinking feature will process each page and automatically add links to key phrases and words.

UseFlyoverPopups

When set to "Y", Flyover Popups will be used.



RTF Specific Options

[RTF Options]

FileName

The rtf file name, without an extension.

HeadingsStartOnNewPage

When set to "Y", each Heading will begin on a new page.

TopicsStartOnNewPage

When set to "Y", each Topic will begin on a new page.

FirstTopicAfterHeadingStartsOnNewPage

This is normally set to "N" so that a Heading will be followed by a Topic on the same page, but when set to "Y", the first topic that follows a heading will start on a new page.

IncludePageNumbersInHeader

If both this option and the next footer option are set to "N" then page numbers will not be included. Setting this option to "Y" will include page numbers in the Header.

IncludePageNumbersInFooter

When set to "Y", the page numbers will be included in the Footer.

OptimizeCompileTime

If set to "N", then only pages that have been changed will be processed. When set to "Y", all pages will be refreshed.

PrintEditableHeadings

Normally, Headings do not have any help text but editable headings are similar to topics, so if you use editable headings that you want included in your document, set this option to "Y".

ConvertBMPsToJPGs

Bitmaps are generally larger than JPGs, so when you have images embedded in your document, rather than stored externally, it can reduce the size of your file if you set this option to "Y".

ConvertAnyPNGImagesToJPG

MS Word can sometimes deal with PNG images poorly. This only affects some PNG files, but if it affects you then setting this option to "Y" can get around it.

StoreImagesExternally

If this option is set to "Y", then images will be referenced externally in the rtf file. This creates a small file. This is not a normally a problem when working locally, but when you want to distribute the rtf file to someone else, you will want to set this option to "N", so that images are embedded.

SaveStyleNames

When set to "Y", the style names used within Fast-Help will be exported to rtf so that programs like MS Word can interpret them.



PDF Specific Options

[PDF Options]

FileName

The pdf file name, without an extension.

Title

The Title of the pdf document.

Compress

Compression in PDF files is not great, but it can be useful in reducing the file size, so setting this to "Y" will attempt to minimize the size of your file.

OptimizeCompileTime

If set to "N", then only pages that have been changed will be processed. When set to "Y", all pages will be refreshed.

PrintEditableHeadings

Normally, Headings do not have any help text but editable headings are similar to topics, so if you use editable headings that you want included in your document, set this option to "Y".

UseLinks

When set to "Y", topic links will be converted into internal pdf links that will help your users to navigate around your PDF document in a similar way to html files.



PocketPC Specific Options

[PocketPC Options]

FileName

The pdf file name, without an extension.

Title

The Title of the pdf document.

Compress

Compression in PDF files is not great, but it can be useful in reducing the file size, so setting this to "Y" will attempt to minimize the size of your file.

OptimizeCompileTime

If set to "N", then only pages that have been changed will be processed. When set to "Y", all pages will be refreshed.

PrintEditableHeadings

Normally, Headings do not have any help text but editable headings are similar to topics, so if you use editable headings that you want included in your document, set this option to "Y".

UseLinks

When set to "Y", topic links will be converted into internal pdf links that will help your users to navigate around your PDF document in a similar way to html files.



wxWidgets Specific Options

[wxWidgets Options]

FileName

The wxWidgets file name, without an extension.

All Other Options

All other options are the same as HtmlHelp Options - see above for more information.



Commenting Out Lines

If you want to add notes to the ini file, for your own purposes, just precede the line with a semi-colon. Fast-Help will ignore all lines that begin with a semi-colon. This option is called "commenting out lines". You can also use it to temporarily ignore some lines that you enable or disable. For example, if you have an entry such as this:

  [Variables]

  PhoneNumber=555-123-456

You might want to change it to a new number temporarily and then change it back later, so it may be more convenient to do the following:

  [Variables]

  ;PhoneNumber=555-123-456

  PhoneNumber=272-938-010