@database "FileConv.guide" @node Main "FileConv.guide" FileConv Version 1.00 (C) 1996 Adrian O' Neill Table of Contents: 1.0 @{"Introduction" link L10} 1.1 @{"Licence" link L11} 1.2 @{"Disclaimer" link L12} 2.0 @{"Installation" link L20} 2.1 @{"System Requirements" link L21} 2.2 @{"Installing FileConv" link L22} 2.3 @{"Un-installing FileConv" link L23} 3.0 @{"CLI Usage" link L30} 3.1 @{"CLI Examples" link L31} 4.0 @{"Workbench Usage" link L40} 4.1 @{"FileConv Window" link L41} 4.2 @{"The Menus" link L42} 4.3 @{"Keyboard Shortcuts" link L43} 4.4 @{"Using FileConv's Automatic features" link L44} 4.5 @{"The Tool Types" link L45} 5.0 @{"Errors/Messages" link L50} 5.1 @{"CLI Based Errors/Messages" link L51} 5.2 @{"Workbench Based Errors/Messages" link L52} 6.0 @{"Miscellaneous" link L60} 6.1 @{"If you find any bugs!" link L61} 6.2 @{"Glossary" link L62} 6.3 @{"Contacting the Author" link L63} 6.4 @{"How FileConv works" link L64} 6.5 @{"Future Developments" link L65} 6.6 @{"Acknowledgements" link L66} All documentation and programs (C) 1996 Adrian O' Neill. Guide for FileConv v1.00 - Guide revision 1.00 @endnode @node L10 "1.0 Introduction" Introduction FileConv is an easy-to-use program that allows you to take plain ASCII text files produced on your Amiga and change them into a format suitable for use on PC computers. When you normally take a file produced by ed, MEmacs, or any other ASCII based text editor (or word-processor saving in 'plain text' mode), when you try and import the file into Word for Windows, Write, Edit etc. on a PC you may see something like this: The word ProcessorHas forgotten about theEnd of each line FileConv will format the file so that when you import the file, you will see what you originally typed, and not one big long garbled line. At this point, you should note that FileConv cannot read nor write PC disks, you'll need CrossDos or some other method to use PC disks. FileConv can also be used to prepare documents for the WWW - the format that PC text files use is the same format for WWW documents. This especially important if you intend to use 
 tags (or similar).

If needed, FileConv can also transfer PC text files to Amiga format, but
since most Amiga editors happily use PC text files without complaint, you
should not have to use this option too often.

Some important things to note about FileConv:

a) FileConv only works with TEXT files - files not saved using 'text only'
options cannot be handled by FileConv

b) You need to have some way (eg. CrossDos, MessyDos) to write to PC disks
in order to take your converted file to a PC Machine

c) Although FileConv is dead easy to use, it has some very advanced
features that those who transfer many files may wish to read about

d) FileConv is e-mailware - see the @{"licence" link L11}!


Before using FileConv, read and accept the @{"disclaimer" link L12} and @{"licence" link L11}.


    @{"1.1 Licence" link L11}
    @{"1.2 Disclaimer" link L12}

@endnode

@node L11 "1.1 Licence"

                                  Licence

FileConv is e-mailware.  "What?" I hear you cry - well this means that if
you use FileConv and find it useful, you MUST e-mail the author if you have
e-mail facilities.  This is the only usage restriction for private users -
no shareware fees payable! (Well, unless you insist...!)


The reasons for insisting on e-mailing the author are:

a) So I can tell you if FileConv has any important bugs

b) I want to know how (un)popular FileConv is - if many people use it, I
will update if regularly

c) If I develop a newer version, I will let you know

Your e-mail address will be kept private and not passed on to any other
third party - I can't stand junk e-mail either.  Please respect this - if
no-one mails me I'll get lonely :)

Just mail me with what you think of FileConv - that's all you need to do to
register!  Mail me NOW at:

                              aon@bigfoot.com


For redistribution purposes, FileConv can be considered Freely
Distributable, subject to the following:

a) If you redistribute FileConv, the WHOLE archive must be distributed,
including all documentation, unaltered in any way

b) FileConv must not be sold for profit, except for distribution costs

c) If FileConv is to appear in any compilation (except Fred Fish),
coverdisk, fanzine etc. written permission must be obtained first

d) FileConv and it's related documentation is Copyright (C)1996 Adrian O'
Neill.

Source is freely available - @{"Contact the Author" link L63}

@endnode

@node L12 "1.2 Disclaimer"

                                Disclaimer

PROGRAM DISCLAIMER: THE PROGRAMS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF
ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
THE ENTIRE RISK AS TO THE RESULTS AND PERFORMANCE OF ANY PROGRAM IS ASSUMED
BY YOU.  Should the program prove defective, you (and not Commodore or its
dealers or the author of FileConv) assume the entire cost of all necessary
servicing, repair, or correction.  Further, neither Commodore nor the
author of FileConv warrants, guarantees, or makes any representations
regarding the use of, or the results of the use of, the program in terms of
corrections, accuracy, reliability, currentness, or otherwise; and you rely
on the program and results solely at your own risk.

Yes I did steal this from DICE... (sorry!)
Does anyone actually read this?  Does anyone actually understand this?

@endnode

@node L20 "2.0 Installation"

                               Installation

This chapter explains how to install FileConv on your system.  Unlike most
Amiga programs these days, FileConv actually does not require any advanced
editing of startup-files etc. - FileConv is relatively easy to install.

If you experience any problems installing or trying to run FileConv, please
feel free to @{"contact me" link L63}.


    @{"2.1 System Requirements" link L21}
    @{"2.2 Installing FileConv" link L22}
    @{"2.3 Un-installing FileConv" link L23}

@endnode

@node L21 "2.1 System Requirements"

                            System Requirements

The FileConv distribution contains two different versions of the main
program for use:

a) A version for those using Workbench/Kickstart version 1.3

b) A version for those using version 2.0 or higher

For those using 1.3, FileConv can only be used from the CLI - The Workbench
version is only available to those using 2.0 or higher.

FileConv requires very little in the way of memory - 0.5MB will easily
suffice.  Installing to a hard disk drive is recommended, but certainly not
essential - I don't even have one and I wrote the program!

FileConv also will run (reasonably) happy on a machine with one disk drive.

The only system requirements are:

a) The correct version of FileConv is installed for the particular machine
that FileConv is running on

b) If the 2.0 plus version is being used, asl.library MUST be in the libs:
directory - expect crashes if it is not...

@endnode

@node L22 "2.2 Installing FileConv"

                            Installing FileConv

To start with, this is not as hard as it looks!  I am going through this
very slowly, for the benefit of anyone new to this type of thing.

If you have any trouble, do not hesitate to @{"contact me" link L63}!  I will try my best
to be able to help you!

First, the following files should be in the distribution:

FileConv.guide              -   You're reading this!
FileConv.guide.info         -   .info file for this manual
README                      -   You should have read this first
README.info                 -   .info file for the readme file
FileConv_1.3                -   The program for those running 1.3
FileConv_2.0                -   The program for 2.0 and above
FileConv_2.0.info           -   .info file for 2.0 program

I advise you place all these in RAM: (The Ram Disk) before beginning.  You
will have to 'show all files' (in the Workbench 'Window' menu) to see some
of these files.  (You won't be able to see the files ending in .info, but
that doesn't matter).

Once you are sure you have all the files (If you receive FileConv without
any of the above files, contact me immediately), you can begin.

1. Find out which version of Workbench you are using.  This will be on the
original disks you received from Commodore.  It will possibly be one of the
following:

    1.2, 1.3, 2.0, 2.04, 2.05, 2.1, 3.0, 3.1, 4.0 (I Wish...)

2. If you are using 1.2, sorry!  I don't think FileConv will work - Try
installing the 1.3 version, and let me know how you get on!

3. If you are using 1.3, follow this link to @{"install the 1.3 version" link L221} of
FileConv.

4. If you are using 2.0 or anything above this, you will need to @{"install" link L222}
@{"the 2.0 version" link L222} of FileConv.

@endnode

@node L221 "2.2.1 Installing the 1.3 version"

                        Installing the 1.3 version

The 1.3 version can only be used from the CLI - you cannot use the
Workbench based functions.

To install the 1.3 version, all you have to do is:

1. Copy the file 'FileConv_1.3' to your C: directory.  From the CLI, the
command would be:

                         copy ram:FileConv_1.3 C:

(you would of course put something else instead of ram: if you didn't
unarchive this distribution there!)

2. Rename the copied file 'FileConv'.  The command is:

                     rename C:FileConv_1.3 C:FileConv

3. If you have enough room on your disk, you can install this guide - just
create a new drawer (called FileConv or something) on your Workbench disk
and drag the FileConv.guide across to it.

There.  That wasn't so hard now, was it...

@endnode

@node L222 "2.2.2 Installing the 2.0 version"

                        Installing the 2.0 version

Just follow the following steps...

1. If you do not have a hard disk drive, then you will need a disk with at
least 200k of free space.  If you only have one disk drive, then I would
recommend that you make a copy of your Workbench disk and delete files
until you have about 200k of space free - see your Workbench manual for
details on how to delete files from a copy of your Workbench disk.

2. Make a new drawer on your disk.  Call it FileConv.

3. Drag the files README, FileConv.guide and FileConv_2.0 to your new
drawer.

4. The file 'FileConv_2.0' which you have just copied needs to be renamed
'FileConv'.

There! Finished.  Those of you who want to use FileConv from the CLI will
have to @{"read on" link L223}, but this shouldn't apply to many of you.

@endnode

@node L223 "2.2.3 Installing 2.0 for CLI Usage"

                       Installing 2.0 for CLI Usage

You really don't need to use FileConv from the CLI if you have the
Workbench version, but for those of you who want to, you will have to do
this:

The following line needs to be added to your s:user-startup file:

PATH  ADD

Where  is the drawer you created to place FileConv in.

For example, if you created the drawer hd0:Utilities/FileConv you would add
the line

PATH hd0:Utilities/FileConv ADD

to the s:user-startup file.

I will not explain this, but ask for help if you need it...!

@endnode

@node L23 "2.3 Un-installing FileConv"

                          Un-installing FileConv

What would you want to do that for?!

If you installed the @{"1.3 version" link L221}, simply delete the file you copied across,
i.e. delete C:FileConv, along with this guide if you copied it also.

For those who installed the @{"2.0 version" link L222}, simply delete the FileConv drawer
and all of the files in it.

If you @{"altered you user-startup file" link L223}, then remove the PATH line referring
to FileConv.  If you didn't understand that last line, then don't worry -
you don't have to do anything.

@endnode

@node L30 "3.0 CLI Usage"

                                 CLI Usage

The CLI version should only be of interest to those of you who are using
the version for Workbench 1.3 - those using the 2.0 version of FileConv,
you should use the Workbench version.

The CLI parameters are:

    FileConv {[-p]|[-a]} filename {, filename ...} [dest directory]

Where:
    -p:         Convert files to PC format
    -a:         Convert files to Amiga format
    filename:   Files to convert
    dest dir:   Where to put converted files

(If you need reminding of this, type 'FileConv ?' and a help screen will be
displayed)

FileConv will read the files listed.  If you do not specify a format to
convert to (using either -p or -a) then each file will be examined, and
converted to whatever the suitable format is.

If you specify a destination directory, then the converted files will be
placed in this directory.  Otherwise, the converted file will be placed in
the same directory as the original file.

If FileConv converts a file into PC format, it will append the extension
'.pc' to the converted file.  If FileConv converts a file into Amiga
format, it will append the extension '.ami' to the converted file.

Note that currently, FileConv does not understand wildcard characters: you
must only enter filenames.

Read the @{"Examples" link L31} page for more information.  See @{"CLI Based Errors/Messages" link L51}
for more information on the errors and messages that may appear.


    @{"3.1 CLI Examples" link L31}

@endnode

@node L31 "3.1 CLI Examples"

                               CLI Examples

Some examples to help you understand how FileConv works:

Assume the directory Data:amigafiles/ contains files created on an Amiga
text editor.
Assume the directory Data:pcfiles/ contains files created on a PC text
editor.

The following illustrates what would happen if the following commands were
entered on the CLI:


FileConv -p Data:amigafiles/amidoc1

The file doc1 would be converted into PC format (-p) and saved in the file
Data:amigafiles/amidoc1.pc


FileConv Data:amigafiles/amidoc1

The file doc1 would be converted into PC format and saved in the file
Data:amigafiles/amidoc1.pc


FileConv -a Data:pcfiles/doc1.txt

The file doc1.txt would be converted into Amiga format (-a) and saved in
the file Data:amigafiles/doc1.txt.ami


FileConv Data:pcfiles/doc1.txt

The file doc1.txt would be converted into Amiga format and saved in the
file Data:amigafiles/doc1.txt.ami


FileConv -a Data:pcfiles/doc1.txt ram:

The file doc1.txt would be converted into Amiga format (-a) and saved in
the file ram:doc1.txt.ami


FileConv Data:pcfiles/doc1.txt Data:amigafiles/amidoc1 ram:

The file doc1.txt would be converted into Amiga format and saved in the
file ram:doc1.txt.ami
The file amidoc1 would be converted into PC format and saved in the file
ram:amidoc1.pc


FileConv -a Data:pcfiles/doc1.txt Data:amigafiles/amidoc1 ram:

The file doc1.txt would be converted into Amiga format and saved in the
file ram:doc1.txt.ami
The file amidoc1 would not be converted as it is already in Amiga format.

@endnode

@node L40 "4.0 Workbench Usage"

                              Workbench Usage

Using FileConv from the Workbench is simple.  If you are not sure what
FileConv actually does, please read the @{"Introduction" link L10} first.

FileConv has some advanced features - If you use FileConv regularly, then
you should read all of the sections below, but here is a short example of
how FileConv is normally used:

Start FileConv up.  The window should appear on your screen as described
@{"elsewhere" link L41}.  First, click on the @{"In File..." link L421} button.  FileConv will now ask
you to find the file that you want to convert.  Select the file, and click
on OK.

FileConv will now display the format that the file is in.  Now click on the
@{"Out File..." link L422} button.  This will bring up another requester asking for you to
give the new converted file that FileConv will produce a name.  Enter a
suitable filename.

FileConv will have automatically chosen the format that you want to convert
the file to, so all you have to do is click on @{"Convert" link L424} and the file will be
converted while-u-wait!

Read the section on @{"Errors and Messages" link L52} for information on any Errors or
other information FileConv may give you.  For more help, read the sections
below.


    @{"4.1 FileConv Window" link L41}
    @{"4.2 The Menus" link L42}
    @{"4.3 Keyboard Shortcuts" link L43}
    @{"4.4 Using FileConv's Automatic features" link L44}
    @{"4.5 The Tool Types" link L45}

@endnode

@node L41 "4.1 FileConv Window"

                              FileConv Window

When FileConv is first started, the initial window will appear on your
screen.  This screen has the following buttons:

    @{"In File... Button" link L421}
    @{"Out File... Button" link L422}
    @{"Convert Button" link L424}
    @{"Iconify Button" link L426}
    @{"Quit Button" link L425}

Click on the relevant line above to find out what each of the buttons do.
Some of these buttons also have @{"keyboard shortcuts" link L43}, and they can also be
accessed by using the @{"menus" link L42}.

The window also has two lines beside the @{"In File..." link L421} and @{"Out File..." link L422}
buttons.  The first line allows you to type the name of the file that you
want to convert - this line will be automatically filled in when you use
the @{"In File..." link L421} button to select a file to convert.  The second line allows
you to type the name of the new converted file - this will also be
automatically filled in if you use the @{"Out File" link L422} button to select an output
file.

Beneath these two buttons is the File Format indicator.  This shows what
format the input file is in.  Once you select a file to convert, FileConv
will look at the file and show what format the file is in.  FileConv will
tell you that the file is in one of the following formats:

           You haven't selected a file to convert yet
    PC/CPC          The file is a PC or Amstrad CPC Text file
    Amiga/UNIX      The file is an Amiga or UNIX Text file
    Unsuitable      FileConv cannot convert this file

Beside this is a cycle-gadget that allows you to select what format you
want the file converted to - either Amiga/UNIX or PC/CPC.  This gadget is
automatically set whenever an In File... is selected.

The window also has a Close gadget and a Depth gadget (see your Amiga
manual for more information on these).  If you select the Close gadget, the
window will @{"iconify" link L426}.

@endnode

@node L42 "4.2 The Menus"

                                 The Menus

FileConv has two menus.  The Project menu allows you to perform simple
tasks, the Options menu controls the more advanced features of FileConv.

For more information on what each of the menus do, click on the appropriate
line below:

        The Project Menu:

            @{"In File..." link L421}
            @{"Out File..." link L422}
            @{"About" link L423}
            @{"Convert" link L424}
            @{"Quit" link L425}

        The Options Menu:

            @{"Iconify" link L426}
            @{"Automatic" link L427}
            @{"Auto Convert to" link L428}

These menu items also have @{"Keyboard Shortcuts" link L43}.

@endnode

@node L421 "4.2.1 In File..."

                                In File...

This will bring up a standard Amiga File Requester asking you for the
location of a file that you want to convert.  For more information on the
Amiga File Requester, see your Workbench manual.

FileConv will place the filename in the line beside the In File... button.
FileConv will also inform you of the format of the file, as well as
automatically selecting a format that the file should be converted to.

@endnode

@node L422 "4.2.2 Out File..."

                                Out File...

This will bring up a standard Amiga File Requester asking you for the name
of a file that you want FileConv to create, i.e. the location of the new
converted file.  For more information on the Amiga File Requester, see your
Workbench manual.

FileConv will place the filename in the line beside the Out File... button.

@endnode

@node L423 "4.2.3 About"

                                   About

This will bring up a window with copyright information and the version
number of FileConv.

@endnode

@node L424 "4.2.4 Convert"

                                  Convert

This will begin the conversion process.

Before you can begin to convert a file, you must make sure that you have
selected both an @{"In File..." link L421} and an {"Out File..." link L422} either by typing the
filenames in or by using the file requester.

The Input file must be in a recognisable format, and the appropriate output
format selected.

IF FileConv determines that everything is fine, then it will take the file
specified in the line beside the @{"In File..." link L421"}, convert it into the format
specified and save the results in the file specified next to the @{"Out" link L422}
@{"File..." link L422} button.

If something is wrong, then FileConv will @{"let you know" link L52}.

If the conversion succeeded, then FileConv will display the message
"Conversion Done".

@endnode

@node L425 "4.2.5 Quit"
                                   Quit

This will close the application.  FileConv will @{"ask for confirmation" link L5211} before
it quits.

@endnode

@node L426 "4.2.6 Iconify"

                                  Iconify

This will close the FileConv window, and replace it with a small icon on
the Workbench screen.  To open the FileConv window again, double-click on
the FileConv icon.

The behaviour of FileConv when it is iconified depends on whether or not
the @{"Automatic" link L427} mode has been selected in the Options menu.  If this has been
selected, then refer to the section on @{"Using FileConv's Automatic features" link L44}
for more information.

By default, the @{"Automatic" link L427} mode is not selected.  In this case, when
FileConv is iconified, you can drag a file onto the FileConv icon and the
FileConv window will open complete with the name of the file you dragged
onto the icon in the @{"In File..." link L421} line.

@endnode

@node L427 "4.2.7 Automatic"

                                 Automatic

This menu item allows you to either select or de-select Automatic mode.  If
a check-mark is beside the Automatic menu item then Automatic mode is on.
If there is no check mode then Automatic mode is off.

Automatic mode determines what FileConv will do when @{"Iconified" link L426}.  If
Automatic mode is off, then FileConv will behave as described in the
section on @{"Iconifying" link L426}.  If however Automatic mode is on, then refer to the
section on @{"Using FileConv's Automatic features" link L44} for more information on what
FileConv will do.

@endnode

@node L428 "4.2.8 Auto Convert to"

                              Auto Convert to

This menu item is used in relation with the @{"Automatic" link L427} features of FileConv.
It specifies the format that you want files automatically converted to.

Refer to the section on @{"Using FileConv's Automatic features" link L44} for more
information.

@endnode

@node L43 "4.3 Keyboard Shortcuts"

                            Keyboard Shortcuts

There are two types of keyboard shortcuts - Menu and Button.  To use either
of these shortcuts, you must have the FileConv window selected, and you
must not be entering text in the window.

The Button shortcuts allow you to use the buttons without clicking on them.
To use, all you have to do is press the key indicated by an underlined
letter in each of the buttons whilst holding down either Alt key.  They are
as follows:

        I       -       @{"In File... button" link L421}
        O       -       @{"Out File... button" link L422}
        T       -       Convert to cycle gadget
        C       -       @{"Convert button" link L424}
        Q       -       @{"Quit button" link L425}


The Menu shortcuts allow you to use the menus without using the mouse.  To
use, all you have to do is hold down the Right-Amiga key (see your manual)
and press the letter indicated below.  The menu shortcuts are also
indicated beside each menu item.

    Shortcuts for the Project Menu:

        I       -       @{"In File..." link L421}
        O       -       @{"Out File..." link L422}
        C       -       @{"Convert" link L424}
        Q       -       @{"Quit" link L425}

    Shortcuts for the Options Menu:

        A       -       @{"Iconify" link L426}

@endnode

@node L44 "4.4 Using FileConv's Automatic features"

                    Using FileConv's Automatic features

Before you start, you should know that this feature, although complex, is
extremely useful if you intend to use FileConv for converting many files at
the one time - it may look complicated, but it could save you time if you
become a FileConv power user!

FileConv has the ability to convert many files at once.  This feature is
enabled if Automatic mode is enabled - to enable it, ensure that there is a
check next to the @{"Automatic" link L427} menu item (in the Project menu).

In order to convert the files, FileConv must know what format you want the
files changed to - select the appropriate format using the menu item @{"Auto" link L428}
@{"Convert to" link L428} (also in the Project menu).  When converting multiple files,
FileConv can only convert to the one format, so you must make sure that all
the files you want to convert are in the one format.  If they are not,
FileConv will simply ignore any files that are in the incorrect format.

Once you have completed the above two steps, select @{"Iconify" link L426} which will
close the FileConv window and place the FileConv icon on the Workbench.

Normally, when you drag a file onto the FileConv icon, the FileConv window
will open with the filename in the @{"In File..." link L421} line.  This does not happen
when Automatic mode is enabled.

When Automatic mode is enabled, you can drag many files onto the FileConv
icon at once.  To do this, multiple select the files you want to convert on
the Workbench screen (i.e. Click on the first file, hold down shift, click
on the second, third etc. - see you Workbench manual for more information),
position the pointer over the FileConv icon and let go!

FileConv will now try and convert each of the files you selected to the
format that you specified under the Auto Convert to menu item.

For each file in the correct format, FileConv will bring up a file
requester asking for a name to save the converted file as.  The default
will be the original file name plus an extension of either ".ami" if the
file will be converted to Amiga format, or ".pc" if the file will be
converted to PC format.  Enter a name or click on OK to accept the default.
If you do not want this particular file to be converted, then click on
Cancel.

If the file is not in the correct format, FileConv will @{"display a requester" link L527}
telling you of this.

After all the files have been dealt with, a @{"summary of the conversion" link L5212}
@{"process" link L5212} will be displayed.

@endnode

@node L45 "4.5 The Tool Types"

                              The Tool Types

The Tool Types allow you to control FileConv's more unusual functions.  You
should understand how to add and remove Tool Types before you read this
section - consult your Workbench manual.

The Tool Types that FileConv recognises, along with their purpose is shown
below:


1.  ICONIFY

Usage: ICONIFY

If this Tool Type is present, then FileConv will automatically @{"iconify" link L426} upon
startup:  This is useful in conjunction with the AUTO Tool Type.


2.  BUFFER

Usage: BUFFER=
        Where  is an integer in the range 2048 - 20480

This Tool Type is useful for those with only one disk drive.  It determines
how large the file buffer is - you may wish to have a Tool Type along the
lines of
                               BUFFER=10000
if you have only one disk drive.  This will mean fewer disk swaps.  The
default is 2048.  Note that a larger  will require more memory.
3.  AUTO

Usage: AUTO=YES or
       AUTO=NO

This Tool Type will determine the initial state of the @{"Automatic menu item" link L427}.
If this Tool Type is set to YES then the Automatic mode will be enabled
(check-mark on) otherwise Automatic mode will not be enabled.

If the Automatic mode is changed whilst FileConv is running, this Tool Type
will be changed whenever the program is exited.


4.  CONVERTTO

Usage: CONVERTTO=AMIGA or
       CONVERTTO=PC

This Tool Type will determine the initial state of the @{"Auto Convert to menu" link L428}
item.  If this Tool Type is set to AMIGA then the menu item will be set to
Amiga format, otherwise it will set to PC format.

If the Auto Convert to menu item state is changed whilst FileConv is
running, this Tool Type will be changed whenever the program is exited.


5.  INDIR

Usage: INDIR=
        Where  is an Amiga path

This sets the initial path that appears in the file requester whenever the
@{"In File..." link L421} operation is selected.  This is useful if you always convert
files from a certain directory, for example, those using MessyDos may find
that using the Tool Type
                                INDIR=MS0:
may come in handy.


6.  OUTDIR

Usage: OUTDIR=
        Where  is an Amiga path

This sets the initial path that appears in the file requester whenever the
@{"Out File..." link L422} operation is selected.  This is useful if you always convert
files to a certain directory.

@endnode

@node L50 "5.0 Errors/Messages"

                              Errors/Messages

Of course you will experience some sort of errors...

    @{"5.1 CLI Based Errors/Messages" link L51}
    @{"5.2 Workbench Based Errors/Messages" link L52}

@endnode

@node L51 "5.1 CLI Based Errors/Messages"

                       5.1 CLI Based Errors/Messages

CLI Errors:

1. @{"*** Fatal Error: you have specified more than one format!" link L511}

2. @{"*** Fatal Error: you have specified more than one directory!" link L512}

3. @{"*** Fatal Error: no files specified to convert!" link L513}

4. @{"*** Error: Unable to read file " link L514}

5. @{"*** Error: Unable to open  for writing" link L515}

6. @{"*** Error: File  is not suitable for converting" link L516}


CLI Messages:

1. @{"... not converted - file is already in PC format" link L517}

2. @{"... not converted - file is already in Amiga format" link L518}

3. @{"... converted to Amiga format" link L519}

4. @{"... converted to PC format" link L5110}

@endnode

@node L511 "5.1.1 Cli Error #1"

         *** Fatal Error: you have specified more than one format!

You have specified both the -a and -p formats on the command line.  You
cannot convert files to both formats - you must either specify -p or -a,
not both.

@endnode

@node L512 "5.1.2 Cli Error #2"

       *** Fatal Error: you have specified more than one directory!

You have entered two destination directories on the CLI - FileConv can only
put the converted files in one directory, two directories doesn't make any
sense.

@endnode

@node L513 "5.1.3 Cli Error #3"

              *** Fatal Error: no files specified to convert!

You must specify at least one file to convert!  What more can I say?

@endnode

@node L514 "5.1.4 Cli Error #4"

                   *** Error: Unable to read file 

FileConv is unable to read the .  This could happen because:

a) The file does not exist - check your spelling!

b) You have used wildcard characters expecting FileConv to interpret them -
sorry, FileConv currently can't do that!

c) There is something wrong with the file, perhaps caused by a disk error

d) The 'read' attribute of the file is not set - see your Workbench manual

e) You have not entered the correct directory for the file - If a file is
in ram:, unless your current directory is ram: you must put 'ram:' before
the file name

@endnode

@node L515 "5.1.5 Cli Error #5"

               *** Error: Unable to open  for writing

FileConv cannot write to the specified file.  This may be because:

a) The disk is full

b) The volume does not exist, eg. typing rag: instead of ram:, or ram
instead of ram: (the colon is important) as a destination directory

c) Disk error

d) Write-protected disk

@endnode

@node L516 "5.1.6 Cli Error #6"

           *** Error: File  is not suitable for converting

FileConv has examined the , and determined that it is not purely a
text file.  Remember that FileConv can only transfer plain ASCII files -
read the @{"Introduction" link L10} for more information on what type of files FileConv
can handle.

@endnode

@node L517 "5.1.7 Cli Message #1"

          ... not converted - file is already in PC format

You have requested FileConv to transfer the  to PC format - FileConv
has refused since it has examined the file and concluded that it is already
in a format suitable for use by a PC.  The file will not be converted.

@endnode

@node L518 "5.1.8 Cli Message #2"

         ... not converted - file is already in Amiga format

You have requested FileConv to transfer the  to Amiga format -
FileConv has refused since it has examined the file and concluded that it
is already in a format suitable for use by an Amiga.  The file will not be
converted.

@endnode

@node L519 "5.1.9 Cli Message #3"

                    ... converted to Amiga format

FileConv has transferred the text file to a format suitable for use by
Amiga computers.  To find out where FileConv has placed the converted file,
read the section on @{"CLI Usage" link L30}.

@endnode

@node L5110 "5.1.10 Cli Message #4"

                     ... converted to PC format

FileConv has transferred the text file to a format suitable for use by PC
computers.  To find out where FileConv has placed the converted file, read
the section on @{"CLI Usage" link L30}.

@endnode

@node L52 "5.2 Workbench Based Errors/Messages"

                    5.2 Workbench Based Errors/Messages

Workbench Errors:

1. @{"Error: Couldn't open  for reading - check spelling in requester!" link L521}

2. @{"Error: Couldn't open  for writing - check spelling in requester!" link L522}

3. @{"Error: The file  is not suitable - use only plain ASCII files" link L523}
   @{"please!" link L523}

4. @{"You must specify both an Input and Output file before Conversion can" link L524}
   @{"begin!" link L524}

5. @{"You cannot specify a directory/volume for an input/output file!" link L525}

6. @{"This seems to me to be a pretty pointless operation...!" link L526}

7. @{"The file  Cannot be converted because it is already in the correct" link L527}
   @{"format!" link L527}

8. @{"Problem Iconifying (Perhaps missing .info file?)" link L528}


Workbench Messages:

1. @{"Warning! You are about to overwrite an existing file! Are you sure you" link L529}
   @{"want to Proceed?" link L529}

2. @{"Conversion Done" link L5210}

3. @{"Are you sure you want to quit?" link L5211}

4. @{"Operation Complete ..." link L5212}

@endnode

@node L521 "5.2.1 Workbench Error #1"

  Error: Couldn't open  for reading - check spelling in requester!

FileConv is unable to read the .  This could happen because:

a) The file does not exist - check your spelling!

b) You have used wildcard characters (for example, #, ? etc.) expecting
FileConv to interpret them - sorry, FileConv currently can't do that!

c) There is something wrong with the file, perhaps caused by a disk error

d) The 'read' attribute of the file is not set - see your Workbench manual

@endnode

@node L522 "5.2.2 Workbench Error #2"

  Error: Couldn't open  for writing - check spelling in requester!

FileConv cannot write to the specified file.  This may be because:

a) The disk is full

b) Disk error

c) Write-protected disk

@endnode

@node L523 "5.2.3 Workbench Error #3"

Error: The file  is not suitable - use only plain ASCII files please!

FileConv has examined the , and determined that it is not purely a
text file.  Remember that FileConv can only transfer plain ASCII files -
read the @{"Introduction" link L10} for more information on what type of files FileConv
can handle.

@endnode

@node L524 "5.2.4 Workbench Error #4"

You must specify both an Input and Output file before Conversion can begin!

You have asked FileConv to start converting but you have forgotten to give
FileConv either the name of a file to convert, or the name of the new,
converted file that FileConv will create for you.  You must fill both of
these in before a conversion can begin.

@endnode

@node L525 "5.2.5 Workbench Error #5"

      You cannot specify a directory/volume for an input/output file!

You have not entered a filename in one of the requesters.  You have in fact
entered a directory name - see your Workbench manual for the difference
between files and directories - FileConv only works with files.

@endnode

@node L526 "5.2.6 Workbench Error #6"

          This seems to me to be a pretty pointless operation...!

FileConv has analysed the file you wish to convert.  You have asked
FileConv to convert the file into it's own format - this will, in effect do
nothing with the file.  Check you are using the correct file, or change the
format you want the file converted to.

@endnode

@node L527 "5.2.7 Workbench Error #7"

 The file  Cannot be converted because it is already in the correct
                                  format!

This will appear when performing @{"automatic" link L44} or multiple conversions.

FileConv has analysed a particular file you wish to convert.  You have
asked FileConv to convert this particular file into it's own format - this
will, in effect do nothing with this file.  This file will not be
converted.

@endnode

@node L528 "5.2.8 Workbench Error #8"

             Problem Iconifying (Perhaps missing .info file?)

FileConv is having trouble @{"iconifying" link L426}.  This is most probably because
there is something wrong the FileConv.info file - this is necessary to
iconify.  Other (less probable) reasons may be:

a) You have too many icons on the Workbench screen (perhaps if you are
   using ToolManager)

b) Low memory

@endnode

@node L529 "5.2.9 Workbench Message #1"

Warning! You are about to overwrite an existing file! Are you sure you want
                                to Proceed?

In the @{"Out File..." link L422} field you have specified a file that exists already.
If you click on 'Yes', the file will be overwritten - you will lose the
original contents.  Clicking on 'No' will cause the conversion to be
cancelled.

@endnode

@node L5210 "5.2.10 Workbench Message #2"

                              Conversion Done

The conversion has been completed successfully.  The new, converted file
will be found in the place you specified in the @{"Out File..." link L422} field.  But
of course you should know this already!

@endnode

@node L5211 "5.2.11 Workbench Message #3"

                      Are you sure you want to quit?

Asked upon requesting to @{"Quit" link L425}.  Click on 'Yes' to leave FileConv, 'No' to
stay and admire the cool graphics.

No conversion will be done if you quit - take care!

Any changes made to the 'Options' menu will be saved when you quit.

@endnode

@node L5212 "5.2.12 Workbench Message #4"

                    Operation Complete
                        Files converted:        
                        Files not converted:
                          Already formatted:    
                          Cancelled/Other:      

This will appear after an @{"automatic" link L44} or multiple conversion.  It is
basically a summary of the conversions performed.

The first number will show the number of files successfully converted to
the format that you originally specified.

The second number indicates how many files were not converted because they
were already in the correct format.

The third number shows show many files were not converted because the user
cancelled the conversion, or the file could not be read, or you specified a
directory/volume accidentally etc.

@endnode

@node L60 "6.0 Miscellaneous"

                               Miscellaneous

Stuff that doesn't quite fit anywhere else...


    @{"6.1 If you find any bugs!" link L61}
    @{"6.2 Glossary" link L62}
    @{"6.3 Contacting the Author" link L63}
    @{"6.4 How FileConv works" link L64}
    @{"6.5 Future Developments" link L65}
    @{"6.6 Acknowledgements" link L66}

@endnode

@node L61 "6.1 If you find any bugs!"

                           If you find any bugs!

If you find any bugs in this program, or if you have anything to say about
FileConv (it can be critical - I can take it :) then @{"let me know" link L63} at once!

@endnode

@node L62 "6.2 Glossary"

                                 Glossary

Amiga Text File
    - A text file for use on Amiga computers, roughly equivalent to PC text
files (but not exactly, hence the need for this program!)

ASCII
    - American Standard Code for Information Interchange.  A standard way
of transferring text files between computers, often known as 'text only'.

Automatic Conversion
    - A conversion where many files of the same format are dragged onto the
FileConv icon to be converted all at once to the same format specified
earlier.

PC Text File
    - A text file for use on the PC variety of computers, roughly
equivalent to Amiga text files (but not exactly, hence the need for this
program!)

Text Editor
    - A program such as Ed, Ted, MEmacs or dme which allows the user to
edit text without the use of any formatting such as fonts, sizes etc.

Text File
    - A file made up only of ASCII characters.  This type of file is
automatically produced by any Text Editor, but a Word Processor can produce
this type of file by saving the file as 'ASCII Only' or 'Text Only'.

Wildcard Characters
    - Characters such as # and ? which are used to specify wildcard
patterns.  See your Commodore manual for more information.

@endnode

@node L63 "6.3 Contacting the Author"

                           Contacting the Author

Feel free to contact me if you have anything to say regarding FileConv
(Criticism always welcome), if you spot any bugs, or if you need any help
in installing or using FileConv.

If you want to know how FileConv can help you transfer files to your PC, or
you don't understand something in this guide, mail me now!

Also if you just want to say hi, give me some money, or electronically chat
me up, I can be reached by e-mail, my address is:

                              aon@bigfoot.com

Also look out for me on IRC, I'm untwigged.

@endnode

@node L64 "6.4 How FileConv works"

                            How FileConv works

For the inquisitive, FileConv actually does very little: It simply changes
the End of Line characters in the file it's reading.

When converting from Amiga to PC, FileConv simply replaces the character
CTRL-J (ASCII 10 ($A)) with the character sequence CTRL-M CTRL-J (ASCII
13,10 ($C, $A))

Converting from PC to Amiga is simply the other way around.

To determine what type of file FileConv is reading, it simply reads a line
from the file and looks at the way it is terminated - If it ends in CTRL-J,
it assumes it is an Amiga file, with CTRL-M CTRL-J it assumes it is a PC
file.  Anything else is flagged as an 'unsuitable' file.

FileConv will ignore any other control characters - they will however still
appear in the converted file.

@endnode

@node L65 "6.5 Future Developments"

                            Future Developments

Quite possibly wildcard pattern matching from the CLI may be added to
FileConv in the near future.

If enough interest is shown in FileConv (and indeed, the Amiga as a
computer) then I may eventually get around to redesigning the GUI to allow
the user to select more than one file to convert, convert entire
directories/disks etc.  I may even allow the user to press Help and have
this guide pop up at the correct page.  But don't hold your breath, I am a
student you know (and we do have to do some sort of work!)

The more people mail me, the more chance FileConv will be upgraded!  So if
you haven't registered yet, do it now!


Other projects I plan for the Amiga in the foreseeable future are:

a) Definition and Implementation modules for the Amiga program 'Turbo
Modula-2', so you can use the examples in the book 'An Introduction to
Computer Science with Modula-2' (Adams, Gabrini, Kurtz) - very useful for
university - should be out soon!

b) Z80 assembler (I know its been done a million times before, but I need
it for...)

c) Amstrad CPC Basic Compiler - Perhaps!

d) In the very long term, a usable database program for the Amiga
On the non-Amiga front, I have work in Perl, Java and Javascript, C and
HTML to do, as well as (a little!) university work to do.  So don't be
surprised if I take a while to respond to your mail!

@endnode

@node L66 "6.6 Acknowledgements"

                             Acknowledgements

This program was written using Blitz Basic 2 (v2.1) and would not have been
possible without the imagination of Mark Silby.

Also greatly responsible is Stephen McNamara (of Red When Excited Ltd.)
whose RI Libraries form the basis of the Workbench version.

Thanks also to those on the Blitz-list who gave me help and support.

Chris Knight, who published my first program many moons ago - thanks!

Thank you to anyone who will bother to register this program, especially
those who will tell me what they think of it!


c ya!
    Adrian

@endnode