@#howtousehelpreader
*************************** How to use HelpReader ***************************
* Click MENU on this window to bring up the subject menu, and chose a       *
* subject to move to it. In the text you may find buttons (@%howtousehelpreader#), and if you  *
* click one, the window will move to that reference. Double clicking this   *
* window with ADJUST will take you back through the positions you were in   *
* when you clicked on a button or on the menu.                              *
* TIP: If it doesn't seem to be working, try minimising the window.         *
************************************************* @%helpreader# More on HelpReader ***
@#machine
Machine Requirements

Tabbit requires RISC-OS 3 to run.   It should work when run from a read-only
medium, i.e. a CD or archive.   The faster your processor and disc drive,
the faster your results - but it should run quite happily on an ARM 2 and
was developed for use on an ARM 250. @%speed#    On a 4Mb Archimedes it
requires 32k of free memory to run, and on a 2Mb machine it will run in a
16k wimpslot.   I know of no reason why it should not be StrongARM
compatible but I haven't actually tested that. Tabbit supports Acorn's
interactive Help.

@#purpose
Purpose of Program

This utility was written for a specific purpose and will only rarely be
used.   It performs the opposite of the 'Expand tabs' command in 'Edit' - it
removes multiple spaces and replaces them by tab characters where possible.

Note that a tabwidth of 8 characters. for example, will not replace all
occurrences of eight or more spaces in a text, since tab characters merely
cause columns of text to line up by moving the cursor on to the start of the
next column - however few spaces that may be.

@#use
How to Use the Program

Drag a file to the iconbar.   It doesn't have to be filetyped as a text
file, but tabbing any file which isn't essentially plain text is not a good
idea.   A savebox will pop up.   It will not go away until you click on the
close icon, so you can alter the options from Tabbit's menu, open filer
windows etc.   When you drag the icon to a filer window, Tabbit will display
an hourglass showing the percentage done and start to convert the file.  
When it is done, it will give you a few statistics about that file and then
load it into a text editor so that you can judge the end result.

@#options
Menu Options

      Output to   @%output#
      Tab width   @%width# 
      Options
                Multitasking  @%mult#
                Load result   @%load#
                Auto savebox  @%auto# 

      Process file @%process#   

@#output
If you have closed the savebox, you can use the 'Output to' dialogue box to
alter the destination of the processed text by dragging the icon somewhere
else.   Dragging from this window will not start the conversion process -
click on the iconbar icon or select 'Process text' from the menu.

@#width
The 'Tab width' menu allows you to select tabs to 4 columns, 8 columns, or a
number specified in the writable menu entry.   The smaller the value, the
more substitutions will be able to take place - larger values will enable
the file to be processed more quickly.
'StrongED' only displays 4- and 8-column tabs.   'Edit' only expands tabs to
8 columns.   If you set a value not supported by your text editor, the
appearance of your text may change drastically.

@#mult
The 'Options' menu allows you to alter the default behaviour of the program.
If you select 'Multitasking' the hourglass and percentage will not be
displayed and you will still be able to use the desktop while the file is
being processed.

@#load
If you select 'Load result' your text editor will be run and the file loaded
into it as soon as Tabbit has finished.   This option is on by default since
you will normally want to check that all is well.   Switch it off to save
time and/or memory.

@#auto
If you select 'Auto savebox' a savebox will pop up every time you drag a
file to Tabbit's icon.   Dragging the file icon out of this savebox will
start the processing.   If this annoys you, you can switch this option off
and use the other output alternatives. @%output#    Note that if you do not specify
a save path, the output will be saved into your !Scrap directory.  

@#process
'Process file' will start the conversion process, as will clicking on the
iconbar icon.

@#when
When Tabbit Is Useful

Usually, if you want to format text with flexible tabs rather than by
padding it out with spaces, you do so from the start.   Tabbit would only
normally be used on a file created by someone else, which you wish to edit.

Tabbit was written because the 'Spaces to tabs' function in 'StrongED' only
creates tabs at the beginning of each line - and I had a disc-indexing
program which generated enormous files laid out in two columns, each
directory level indented by two characters further than its predecessor.  
Replacing all the extra spaces by 4-column tabs shortened the files by about
20Kb!
The other situation where a file might be sent through Tabbit is when
it contains tables of data where the columns are formatted with spaces, as
some program documentation does.   Replacing these spaces with tab
characters makes it much easier to edit the table without sending all the
columns out of alignment.   Also, columns laid out using spaces will only
align properly when displayed in a monospaced font such as Corpus or the
system font.   They can only be displayed correctly in most outline fonts
when they are laid out using tabs.

@#problems
Known Problems

Tabbit is not very intelligent.   In order to run at a decent speed without
the benefit of StrongARM, it checks only that a line of text has two or more
consecutive spaces before starting substitution.   This means that any line
with extra spaces, for example after a full stop, may get tabbed, even
where this is not appropriate.
As of version 120, single spaces in the middle of a line will no longer get
tabbed, however!

Tabbit also assumes that lines are 'hard-wrapped' - that there is a return
character at the end of every line.   Files written in 'Edit' or sent over
the Internet are normally like this.   Files written in 'Impression' or
'StrongED' are not.  If the file is not hard-wrapped, Tabbit cannot predict
where the start of the second or third line in a paragraph will come, and so
will probably mis-align the columns.
However, in my experience, the type of file which needs to be sent through
Tabbit is always hard-wrapped anyway.

You cannot save the output file over the input file since they both have to
be open simultaneously.   In any case it is a good idea to check that the
output was as you intended before deleting the original.

@#tech
Technical details

@%error# Conditions triggering error messages

Tabbit simply GETs one string at a time from the source file, analyses
it and saves it out to the destination file.
First it checks whether the line contains extra spaces and hence requires to
be processed.   If it does, it steps through the line examining every {nth}
character, where {n} is the user-defined column width.   If any of the
previous characters are spaces, it deletes them until it comes to either a
non-space character or to the start of the previous column.
It then checks whether any spaces were found, or whether only one space
was found, and then outputs whatever remains of that column, plus a tab
character, if necessary, and goes on to the next column.  At the end of the
line it outputs a linefeed and reads in the next line.
This technique is simple to program and requires a minimal Wimpslot.  
However it is relatively slow, and does mean that Tabbit cannot support
direct RAM transfers either into or out of another application.

The resulting file is filetyped as text and simply run, which automatically
invokes the current text editor.

The percentage display simply compares the total length of the strings read
in so far with the length given in the catalogue information of the source
file.   This is not actually accurate, but serves to indicate how long is
left to wait.

@#null
Tabbit does not null-poll.   Instead, while in 'multi-tasking' mode,
it calls Wimp_Poll once every time around its main processing loop, but
completely ignores the reason code returned... this prevents the user from
altering the options while the file is being processed, while allowing the
WIMP to poll other tasks.   As a result Tabbit ought not to slow down the
desktop just by sitting on the iconbar!

@#history
HISTORY

version 100 - first WIMP version, when I got tired of altering  variables
              and input/output paths in the singletasking version.
version 110 - completely altered the saving/loading conventions after some
              trenchant criticism.   Rearranged menus and added 'Load
              result' option. @%load#  Completely rewrote interactive help.  
              Managed to write Special file for BasCompress.
version 111 - altered saving/loading again.  Completely rewrote HelpReader
              text.   Added 'Auto savebox' option. @%auto#
version 112 - remembered to alter version number from 110 in info window!
              Stopped failed RAM transfers from altering filename/path. Help
              text reconstructed, since the only source file turned out to
              be for the previous, since totally altered version!
version 113 - added an extra menu entry to run HelpReader from within the
              application.
version 120 - Rewrote the central function to behave more intelligently,
              i.e. not to substitute tabs where only a single space is
              required. Less 'structured' programming actually resulted in
              a slight speed increase, despite the extra processing needed!
version 121 - Moved the default save to the (more orthodox) <Wimp$ScrapDir>
              rather than the CSD and ran into problems with OS_GSTrans.


About the author

I write one-off utility programs like this one which tend not to make it
into a fully-WIMPified state.   Tabbit is the name of a soft toy tabby cat.

I am female.   This seems to be unusual enough to be worth mentioning.   I
am also a sociopath.   Believe me, you really _don't_ want to know anything
more....

****************************************************************************

@#error
ERROR MESSAGES GENERATED:

  "You must drag a file to the iconbar first" - no input pathname found
  "The output filename must be different from the input filename since both
   files exist simultaneously" - output pathname same as input pathname
  "Drag icon to a directory viewer" - no output pathname found
  "I don't consider that a sensible tab setting!" - tab width less than 2 or
   greater than 20 characters.
  "Tabbit only tabs single files!"- directory or application dragged to icon
  
  
@#speed
Relative Speeds @%note#  
Substituting tabs for spaces on every line of a 57k file on the hard drive.

                        4-column tabs   8-column tabs

                        single  multi-  single  multi-
                        tasking tasking tasking tasking

ARM2   (Mode 12)        28.39  29.15    17.56  19.62 seconds
ARM250 (Mode 12)        25.38  26.09    15.31  17.66 seconds
ARM610 (Mode 27)         8.3    9.66     5.57   6.82 seconds

N.B. This table is a perfect example of the sort of thing much better laid
out with tabs :(

@#note
Note:
Higher-resolution screen modes (and loading/saving to floppy disc) will
produce dramatically slower timings, as will the presence of null-polling @%null#  
tasks like 'Alarm'!

@#why
Why this isn't a StrongHelp file
I've been told that StrongHelp is now the 'standard' for providing
cross-referenced !Help files.   However, while its multi-window
layout is ideally suited to providing reference information, as the SWI
and Wimp manuals show, I find it less suitable for displaying basic help on
an application.  It is all too easy to miss out on reading about some
feature because the link to it is buried three or four links down from the
root page;  and I always end up with multiple windows scattered all over the
screen.
HelpReader allows you to read through a document from beginning to end,
while still cross-referencing sections and footnotes as required (and
showing a menu of what sections are available).   I find this a more natural
technique.
Finally, you don't need to own and boot a copy of StrongHelp before you can
read this file  and running a HelpReader application is quicker and uses
less memory than loading StrongED/Zap to read a plain text !Help file.
