Help file for "Firepipe" version 201 17th January 2003
This program was developed using Andrew Ayre's "DrWimp" BASIC library,
although it now uses its own WIMP procedures.

Firepipe does not support Acorn's interactive !Help.  The menu options are
too complicated to be explained briefly  read this file.

WHAT THE PROGRAM DOES:
Firepipe converts files from Fireworkz or Wordz format into PipeDream 4
format. Fireworkz can load in PipeDream files, but hitherto there has been
no easy way to convert files in the opposite direction.


HARDWARE REQUIRED TO RUN THIS PROGRAM:
Any Acorn RISC OS computer running RISC OS 31 or above.   A hard disc is not
essential.   Firepipe is RISC OS 5 compatible.

WHAT IS CONVERTED:
Window size/position; caret position;  text, number and array slots; most
formula slots; Names; live date/page number/file name inserts; mailshot
fields

OPTIONS ALSO AVAILABLE TO CONVERT:
Column widths; BaseStyle font name, size, row height and grid on/off 
settings; thousands separator/decimal places format; slot contents wrapped
over several lines; vlookup, hlookup, acos, atan, asin and match functions
translated into their PipeDream equivalents

WHAT IS NOT CONVERTED:
Embedded graphics/charts; row height changes; local column width changes 
(including Tables); colours; Styles (other than some aspects of BaseStyle); 
Effects (other than column auto-width); file date and Name inserts; 
formula_text function is replaced by current contents of slot referred to; 
pathname insert is replaced by current pathname of file; tabs are replaced by 
five spaces; soft hyphens are removed; functions unknown to PipeDream give
"Custom function unknown" errors


HOW TO USE FIREPIPE:
Double-click on the programs icon to load it onto the iconbar.   Drag a
Fireworkz or Wordz file to the iconbar icon to convert it.   A savebox will
pop up suggesting a new name for the converted file.   Simply click on the
"OK" icon to save the file back into the same directory as the original
Fireworkz document;  otherwise you can type in a new name and/or drag the icon
out of the savebox to save the file anywhere you like.   You can even drag it
directly into a PipeDream (or other application) window without bothering to
save the file on disc at all.

Firepipe will now attempt to convert your file to PipeDream format.
Depending on whether you have selected 'Multitasking' from the menu or not,
(see later), an hourglass may be displayed to show the percentage done, or the
status window may appear to the left of the screen to tell you what is
currently happening.   When Firepipe has finished, either the hourglass will
disappear or a message window will pop up to let you know that the file was
successfully converted.   You may find that an icon called 'Rewrap' has
appeared on the left of your iconbar.

You can now load the file.   All the text which was in the Fireworkz version
should still be there, and the formul should still give the same answers;
but it will inevitably look rather different from the original document!
Various options are provided which allow you to imitate Fireworkz as closely
as possible (see below) and you will probably want to use them all.

WINDOWS AND MENUS:
Firepipe has three windows  the Info window (attached to "Info" on the main
menu), the "Save as" window which appears when you have dragged a
Fireworkz file to the iconbar, and the "Status" window which appears when a
file is being converted if you have "Multitasking" ticked on the main menu.

The main menu is reached by clicking the centre mouse button over the iconbar
icon.

"Info" displays the Info window, giving details of the program's version
number, date and author.

"Options" leads to the Options submenu, which controls which aspects of the
Fireworkz file Firepipe will attempt to reproduce.

"Save options" saves the current state (ticked or unticked) of all the menu
options, and the current default column width (see below).   These settings
will be restored next time you load the program.

"Multitasking" controls whether the program takes over the whole computer
while it is converting and saving a file, in order to finish as soon as
possible, or whether it allows you to use other programs while you are
waiting.   If "Multitasking" is selected, a small Status window will appear to
the left of your screen giving a running update on what is happening, and a
warning message will be given to let you know when Firepipe has finished.   If
this option is not selected, the mouse pointer will turn into an hourglass
during the time that Firepipe takes over the computer, and a percentage will
be displayed to indicate how long you will have to wait.   When the file is
complete the pointer will turn back to normal and you will be able to use the
computer again!

Technical note:  Direct RAM transfer to other programs is only possible when
multitasking is off  otherwise transfer via a scrap file will be used.

It is possible to switch off multitasking from the Status window during the
actual conversion of the file  see below.

"Quit", as usual, quits the program.


The Options menu is available from the "Options" entry on the main menu.

"Select all options" will select all the options in this and in the Column
widths menu.   The text will then change to "Clear all options", which will
deselect them all again to give a 'safe' configuration which is almost certain
to preserve all your data but very unlikely to format it correctly!

"Convert functions", if selected, will make Firepipe attempt to translate
the three functions 'vlookup', 'hlookup' and 'match' into a form which will
give the same results as these functions would give in Fireworkz.   Firepipe
can handle nested functions (a lookup inside an if) and several lookups
occurring in the same slot (again, perhaps inside an if).   However, if it
cannot translate them (for example, if the second parameter is not a simple
range) the slot will be output as text, prefixed with the word "Warning:"

The Fireworkz functions 'acos', 'atan' and 'asin' will be translated back
into their non-standard PipeDream equivalents 'acs', 'atn' and 'asn'.

"Column Width" leads to the Width menu controlling the column width options.

"Imitate BaseStyle" causes Firepipe to analyse the first style definition it
meets in the Fireworkz file and to use those settings which translate into
PipeDream equivalents, namely font name, -x and -y sizes, row height, and grid
lines and justification on or off. Whether the actual font is used or not
depends on the setting of the next option.
The "BaseStyle" option is the most complicated of the options provided and
should be the first to be switched off if things go wrong....

"Don't use system font":  this option and the previous option combine to
produce four possibilities.
Imitate BaseStyle	Don't use system font
      ON		      ON		Font defined in style is used.
      OFF		      ON		Homerton font is used.
      ON		      OFF		Row height, etc set, but system font is displayed.
      OFF		      OFF		PipeDream defaults and system font used.

This rather complicated arrangement is provided in order to allow the use of
the system font to be toggled on and off without affecting anything else.   On
my A4000, I find scrolling the screen in PipeDream to be very slow when using
outline fonts and I therefore prefer to use the system font for all
spreadsheet work (and Impression for all DTP work!)   I therefore provided
this option to allow me to override the Fireworkz font settings.

You can also use this option to provide Homerton as a default outline font
if the "Imitate BaseStyle" option causes problems.



"Wrap paragraphs" causes Firepipe to place a space at the beginning of each
text slot.   This ensures that when you give a Format Block command (^EFB)
each slot becomes a separate paragraph, as they were in Fireworkz.   When this
option is set, Firepipe places a PipeDream Command file called 'Rewrap' on the
left of the iconbar as a TinyDir, where it can easily be found and double-
clicked.   Once you have loaded your new PipeDream file, run 'Rewrap' to
rewrap all the slots and then remove the extra spaces.   This reformatting has
to be done from within PipeDream to ensure that all slot references remain
correct  Firepipe cannot do it.
This is the option you are most likely to want to switch off.   In a
spreadsheet it can introduce errors, and in most spreadsheets it serves no
useful purpose.   However, 'Rewrap' is absolutely essential when converting
letter-type documents, where each long paragraph from Fireworkz is crammed into
a single slot!

"Load finished document" causes the converted document to be loaded into
PipeDream as soon as it has been saved, loading up PipeDream if necessary.
It is a good idea to switch this option off if you are dragging files directly
into a PipeDream window, since in this situation Firepipe will end up trying
to run a non-existent file and will complain.

"Analyse number format" attempts to adjust the thousands separator and
number of decimal places used to match the display format of the Fireworkz
document by checking the BaseStyle and Number style if present.   If this
option is not ticked, default values (a comma for the thousands separator
and two decimal places for numbers) will be used.


The Width menu enables you to fine-tune the set of options controlling the way
in which Firepipe tries to reproduce the column widths from Fireworkz. You
would normally keep these options selected, but if they should cause trouble
you have the opportunity to switch them off.


"Set width"          
"Use Basestyle width"
Only one of these two options can apply at a time.  "Set width" allows you
manually to specify the default width for columns for which the Fireworkz
file does not supply it;  "Use BaseStyle width" tries to read the default
width from the initial style definition.   Note that this is not affected
by the setting of "Imitate BaseStyle" on the Options menu;  however, it does
use the same routines to analyse the BaseStyle, so you may need to switch both
these off if you have problems.

In practice the default column width is almost never used, since Fireworkz
spreadsheets tend to be created from a template containing column widths as
Effects, or to have had auto-width applied to them, which also creates an
Effect.   However, if "Check Effects" is not selected, the default width will
come into play.


"Check Effects":  column width Effects are created when you drag the column
boundaries in Fireworkz, or double-click to auto-width them.   Firepipe can
extract these from the file and reproduce them in PipeDream.   Note that for
obvious reasons Firepipe cannot reproduce Effects affecting only part of a
column  perhaps the most common example of this is a Table created by
importing a CSV file.

"Check Styles" is an option to cover the case where a style which affects the
column width is applied over a whole column.   When this option is selected,
Firepipe keeps a list of any styles which define a column width and notes when
they are applied.   I include this option mainly because Gerald Fitton's
ZLine files have been known to use this as a method of column width control 
I doubt that many other people do it.


The Faster menu gives you the option to switch from multitasking to
singletasking while a file is actually being converted  it is not available
at other times.   Clicking MENU over the Status window at this time will reveal
a menu with a single entry reading "Singletasking".   Clicking on this will
cause the computer to ignore everything until it has finished and saved the
file.   In my experience the speed increase is very minor.
Note that this menu item does not affect the setting of the "Multitasking"
entry on the main menu.   Its effects are strictly temporary.

ERRORS
If the program should encounter an error while converting a file, it will
try to save the successfully completed portion of the data to a file
$.FPDump in your root directory.   Depending on the nature of the error, the
FPDump file may be usable in PipeDream or it may not.   If you wish to
experiment, change the filetype to &DDE and load it in - but have a look
at it in a text editor first!

OTHER NOTABLE POINTS:
If you close the "Save as" window before managing to save the file, you can
get it back by clicking SELECT on the Firepipe iconbar icon.

After the file is saved, the window disappears.   However, if you want to
convert the same file again, perhaps with a different set of options, you can
get it back by clicking on the icon again.   


The little grey 'alert window' that pops up to warn you when your file has
finished being converted will stay open for three seconds before
disappearing  click on it to make it close sooner.


You can also open the main menu from the "Save as" window, and options can be
altered right up until the moment when you drag the icon or click on "OK".
(They can, of course, be changed while the file is being converted, but this
will be too late to have any effect on that file.)

If you click on a menu entry leading to a submenu, such as "Options", this
will re-open the menu structure, starting at that submenu, rather than closing
the whole menu structure as would traditionally happen under RISC-OS.   This
helps to prevent Firepipe's menus from hitting the right-hand side of the
screen all the time.


THIS PROGRAM IS FREEWARE:
You may copy it and use it as much as you like and you need not pay me any
money. The program has been compressed to save memory and make it run faster,
but full source code has been provided and programmers may alter the program
if they wish, or copy any ideas or routines they find useful into their own
programs.   All I ask is that you don't distribute copies without the source
code - either my version or your improved version!
