Smart Quotes version 1.20b
 Sam Kington 10th November 1994
See Boring legal message for conditions of distribution.
This program is freeware, *not* public domain  i.e., I retain copyright.

Contents
********

   This le contains the following sections (those marked * are essential to
using Smart Quotes, the others less so):
     * Warning...  this program is RISC OS 3 (or later) only
       Boring legal message  terms of distribution
       About the strange characters...  if this looks strange on a PC
       Im using an Acorn machine...  dont read this in the System font

     * Quotation marks  how quotes work
     * Ligatures and diphthongs  how diphthongs work
     * Typing mistakes  which ones Smart Quotes can correct
     * Menu structure, windows  brief explanation
     * Diphthong menu - what it does
     * Settings window  where you choose types of substitution
       Choices dialogue box  various preferences or choices
       Other choices  more choices
       Characters dialogue box  change the characters used for quotes
     * Diphthongs window  viewing and editing diphthongs
       Using diphthongs  hints and tips for diphthongs
     * Known problems  please read
       How to contact me  says it all really. Address, email, etc. 

   The le Other.MoreInfo contains the following, more obscure stuff:
       What these les actually do  explanation of all the les
       The les you actually need  how to make a smaller Smart Quotes
       Miscellanea  a few things that didnt t anywhere else
       * commands  commands provided by the module
       Variables  special variables used by Smart Quotes
       Changing the font  how to change the default font
       Changes between previous versions  whats been added, changed etc.
       Thanks etc.  various thank-yous, greets, comments, etc.
       Known problems  various problems with other programs etc.
       Wish-list  things I would like to do to Smart Quotes
      
   You may not have a le called Other.MoreInfo, in which case you have a
small version of Smart Quotes. The full version has source code and other
goodies, and should be freely available from the place you got this version.

   The le FileList contains a full list of the les you should have.
      
Warning  Smart Quotes needs the Filter Manager
*********************************************** 

   Smart Quotes works by intercepting key events passed to WIMP
applications, a facility which is only available under RISC OS 3 or later.
It determines which version of RISC OS it is running under by checking
whether the FilterManager is present or not  so if you have RISC OS 3 or
later, type *RMReinit FilterManager at the CLI prompt (F12 or Ctrl-F12) and
try again.

   I am currently aware of four major versions of RISC OS, namely 2.00,
3.00 (early A5000s), 3.10 (most newish machines) and 3.50 (RISC PC). Smart
Quotes will not work on RISC OS 2, will probably work on RISC OS 3.00 (it
was quite buggy, apparently), will denitely work on 3.10 (the version Ive
got), and will very probably work on 3.50  version 1.14 was tested on a
RISC PC, and theres nothing fundamentally different (i.e. it still behaves
the same way).

   If you come across any problems, please contact me (see How to contact
me at the end of this le).

Boring legal message
********************

   This application is freeware, that is, it can be distributed freely as
long as only reasonable charges are made for media and distribution, and as
long as all the files are distributed intact, unmodified (see The les
you may have for a full list of files and lengths)  but see below. I retain
copyright on all program code and documentation.

   One slight exception is the set of library routines Other.ShortHelp,
which may be distributed and used separately (for writing modules for
instance). See the le Other.ShortHDocs for more information.

   You may also freely distribute and use the module MoreHelp. No
documentation is supplied here, but the application !MoreHelp should be
available from the place you got Smart Quotes (if not, send a disc to me and
Ill send it to you, but mail me rst).

   Given the size of Smart Quotes, and particularly the amount of excess
garbage (source code etc.), you are allowed to distribute a useful version
of Smart Quotes, i.e. that produced by running SlimDown on a full version,
provided:
   1) You make it quite clear that this is not the complete version, and that
   the source code and other interesting les are not included in the
   package.
   2) You make it as easy as possible to acquire the extra les.

   This software is supplied asis: I make no warranty, expressed or
implied, of the merchantability of this software or its tness for any
particular purpose. In no circumstances shall I be liable for any damage,
loss of prots, or any indirect or consequential loss arising out of the use
of this software or inability to use this software, even if I have been
advised of the possibility of such loss.

   In other words, if your computer crashes, blows up, you lose all your work
etc. all because of Smart Quotes (unlikely I know), dont blame me.

   If you use this at all, please write to me or e-mail me (see below)
telling me how wonderful or how atrocious it is. Its always nice to hear
from people.

About all these strange foreign characters in this le
*******************************************************

   OK, so if youre reading this on a PC or a Mac or another strange machine
like that, you may be wondering what all these strange ae things are. Well,
theyre quotes (sorry, there was another one), dashes, ligatures, etc.
Honest. But not on all machines...

   Basically, character sets are only standard up to character 127, which is
basically alphanumerics and a few standard punctuation marks. Foreign
characters, typographical oddities like quotes and ligatures, and other more
obscure symbols are non-standard, and each computer often has its own idea
of where they should go in the character set. So dont worry: even if its
hard to read on your current machine, it wont be on an Acorn machine.

Im using an Acorn machine and it still looks strange
*****************************************************

   Thats because youre using the System font. Quotes look OK in the system
font, but dashes and other ligatures or diphthongs look squashed. If youre
reading this in Edit or another editor that knows about outline fonts, change
to an outline font; if youre using Zap, complain bitterly about its lack of
understanding of proportional fonts (if you havent come across this
feature of Zap, try it and be amazed), and load the le into Edit.

   If the lines look spaced out in Edit, set Line spacing to -2 or
something.

   If you want to see why diphthongs are actually useful, use a serif font
(like Trinity) rather than a sans-serif font (like Homerton); even better,
use the Italic version. The difference is quite spectacular.

Quotation marks
***************

   Operation of the program is (hopefully) self-explanatory; the principles
behind it may not be. What the program basically does is sit in the
background, and intercept all the key presses, substituting double and single
quotes according to the current settings, as well as ligatures or
diphthongs. Double quotes are very simple: it just substitutes neutral
quotes () by  and  alternatively, which should be OK in the vast majority
of cases (unless you are using lots of nested quotations). You can of course
turn double quote substitution off, for instance if you are programming, and
leave single quote substitution on.

   The problem is single quotes. Because SmartQuotes has no knowledge of what
you have previously typed, it doesnt know, when you type an apostrophe (),
whether you are starting or closing a quotation (e.g. some text), or
whether the apostrophe is part of a word (e.g. dont). So, if it tries to
substitute single quotes like double quotes, i.e. alternating open and double
single quotes, it will often get it wrong. As most people dont use single
quotes a lot, but use apostrophes all the time, SmartQuotes will
automatically substitute neutral single quotes by apostrophes; however, there
is an option to substitute neutral single quotes alternatively with  and .
Of course, if youre still not satised, you can turn the whole thing off
and stick to double quotes.

   Also, it will often not substitute quotes in a writable icon  keys are
usually handled directly by the WIMP in writable icons, so Smart Quotes
doesnt get to hear about them. You have to insert them manually 
Shift-Adjust-clicking on any of Smart Quotes windows close icon will run
!Chars (or whatever character viewer you have chosen - see Other choices).

Ligatures and diphthongs
************************

   Diphthongs are special characters made out of two other characters stuck
together, like  (a+e). This looks more impressive in upper-case: .
Ligatures are special characters made out of two characters stuck
together, like  (f + i). I cant show you this in upper-case, because
F and I dont stick in upper-case.

   Thats the difference between diphthongs and ligatures (I think - someone
out there who knows much better than I do will probably correct me).
Diphthongs are linguistic combinations, ligatures are typographical
combinations.

   Do not think for a moment that you have to remember this. Its quite a
trivial difference anyway, certainly as far as this program is concerned. In
this documentation, I will use diphthong and ligature to mean the same
thing, a special character made out of two other characters.

   Anyway, Smart Quotes maintains a list of characters and diphthongs (fully
customisable), and scans keypresses like it does for quotes. Whenever two
characters are typed in succession, it looks in its tables to see whether
they should form a diphthong; if they should, it deletes the rst one, and
inserts the required diphthong. So if you type an f, and then immediately
afterwards an i, it will delete the f, and replace the i by the magic
character, . Its all straightforward (to use, anyway).

   Remember, however, that you have to type the two characters in immediate
succession  if you type a hyphen, then something else, then type another
hyphen after it, nothing will happen. To replace a hyphen by an en-dash, you
have to delete it, then type two hyphens.

   Also, when you delete a diphthong, you delete the whole thing. You cant
type , type delete, and end up with a normal f: Smart Quotes knows
youre deleting something, but doesnt know what (you could have moved the
cursor, changed windows, anything). Its a small problem; I hope it doesnt
irritate you too much.

   See Diphthongs window for more details about how to add diphthongs
yourself, and Using diphthongs for more hints and tips.

Typing mistakes
***************

   Typing mistakes, known as typos for short: most of them  are either
wrong capitalisation or transposition of two letters. Short of having a
massive dictionary Smart Quotes cant help you with transposition  and
anyway if youre using this in a word processor you will have a spell checker
, but it can make an intelligent guess at correcting capitalisation.

   What usually happens is this: you have Caps Lock turned off, and you want
to type a word beginning with a capital letter, so you press Shift to make
the rst letter a capital  and then you leave it on too long so the second
letter ends up capitalised as well. Youve usually let it go by the time you
type the third letter, so you end up WIth WOrds THat LOok SOmething LIke
THis. If you have typing mistake checking turned on, and you type two capital
letters at the beginning of a word and then a lower-case letter, Smart Quotes
will replace the second capital letter by a lower-case letter, so you end up
With Words That Look Something Like This.

   This is the option that is least likely to cause you problems, as it
doesnt involve any fancy characters that some programs dont like. Only turn
it off it you will be typing words like NExT a lot of the time, or if case
matters (variable names, SWI names etc.).

Menu structure, windows
***********************

   Smart Quotes now supports interactive help, so I will only explain things
in this le that wouldnt t in the interactive help messages. Interactive
help should by default be turned on; if it isnt, select Interactive help
in the Choices window, available from the menu option Choices... in the
icon bar menu.

Diphthong menu
**************

   Save saves a le called Diphthongs in the directory pointed to by the
variable SmartQuotes$ChoicesDir, which is by default SmartQuotes$Dir but can
be changed to point elsewhere if the Smart Quotes directory is read-only or
restricted access (i.e. on a network) in the Other choices window (see
below). The Diphthongs le is a simple Obey le, so double-clicking on it
will load the diphthongs.

   Refresh: basically, choose this option if you want to make sure the front
end really knows what characters are going to be substituted. Usually it
does, but if you have modied the diphthongs in the command line, or by
double-clicking on another Diphthongs le, you have to tell it the
diphthongs have changed.

Settings window
***************

   The settings dialogue box determines how characters will be substituted.
Choices take effect immediately, so playing around with the different
options and typing to see what happens is usually the best way to work out
what they all mean.

   The dialogue box can take two different forms, depending on the current
choices, which will be reected in the title of the window. The default form
is the graphical form  Show options as icons. You can switch between the
two forms by Adjust-clicking on the windows close icon.

Choices dialogue box
********************

   This dialogue box affects the working of the front-end, and so doesnt
affect substitution of quotes: its mainly cosmetics. Changes take effect
immediately. See also the Other choices window.

   Show next quote in icon: If this option is selected, Smart Quotes icon
on the icon bar, to the left of the Palette, will change from the standard
Quotes icon () to a representation of what double and single quotes would
be represented by (i.e. either an open, double or neutral quote). Again, the
effect is cumbersome to explain in words and very easy to understand when
you can see what is going on  but basically, its main use is to show you
what the next quote is going to be, so if you dont like what it will give
you, you can change the options. It doesnt show ligatures because there are
so many of them.

   Remember quotes state: If selected, when you temporarily disable quotes
substitution by Adjust-clicking on the iconbar icon, Smart Quotes will
remember the state of the quotes, and restore it when you re-enable
substitution; otherwise, it will reset the quotes state to the default
value. So for instance, if you type a double quote (so the next one will be
closed), turn off substitution, do something, then turn it back on, and
type a double quote, if Remember quotes state is on you will get a closed
quote, otherwise you will get another open quote.
   You should select this option if you usually disable substitution to type
something, then re-enable substitution and carry on where you left off.
Conversely, if you usually disable substitution because you typed a smart
quote rather than a neutral quote, and want to avoid that happening again,
when you really *do* want to type a smart quote you will probably want to
start with an open quote, so you should de-select this option.

   Interactive help: If selected, you will get interactive help on all of
Smart Quotes windows and icons; if not, you wont. As mentioned above, this
is supplied with the module More Help, which means it doesnt eat up any of
Smart Quotes memory  it does use some in the Module Area, though.

   Quit kills module: If selected, when you quit the front-end, the
SmartQuotes module will be killed, thus stopping all substitution. If you
want substitution to carry on after you quit the front-end (if you are short
of memory, for instance), turn this option off. Bear in mind, however, that
without the front-end you will need to use the command line (F12 or
Ctrl-F12) to modify the settings; also, when you quit the front-end, you may
have forgotten the module is still running and substituting quotes.
Programmers beware!

Other choices
*************

   The Other choices window is different from the other windows, in that
changes you make in this window do not take effect immediately. This is due
to the special nature of the Other choices window, which is in fact owned
by another application, as it wouldnt t in the main Smart Quotes
application  which explains the disc access when you click on the Other...
button in the Choices window.

   In this window you can change the font styles Smart Quotes uses for the
Diphthongs window, the Edit diphthongs window and the Characters
window; you can change the application to be run when you Shift-Adjust click
on a close icon (the character viewer); and you can change where Smart
Quotes stores its Choices les, if you are running Smart Quotes from a
read-only ling system like a network, a CD or a protected hard disc.

   Full interactive help is provided, so there shouldnt be too many
difficulties. The following comments may be useful:

    You dont have to drag an application to the window to change the
character viewer; you can drag a le as well. (Unfortunately you cannot use a
directory - you cant have everything). The le will be run using *WimpTask,
which will run the le without telling applications  so if you run a Drawle
and Draw (or a similar application) is running, a second copy of Draw will be
loaded. Therefore, the best les to use are Obey, Command, the TaskWindow
equivalents, Desktop or similar les.

    You can change the location of the Choices directory (usually called
SQChoices but you can modify the actual lename by editing the writable
eld); when you click Save and use, if the lename is different the les
will be copied from their old location to their new one. Smart Quotes will
then try and update the Choices le in the (NB) *Smart Quotes* directory 
which may be write-protected. In this case, Smart Quotes will try and save it
in the Scrap directory. This also happens if the new choices directory is
write protected. If you dont have a Scrap directory set up (i.e. you havent
seen Scrap if you have RISC OS 3.1) the save will fail.

    When you modify one of the options, the title bar will change to Other
choices * to show that the choices have been modied.

Characters dialogue box
***********************

   Clicking Default will revert to default settings. An individual character
will also revert to default if the eld is left blank.

   Clicking Save will save the preferred characters to a le called
<SmartQuotes$ChoicesDir>.Chars (see above). This is a standard Obey le,
and so is human-readable and editable (unlike the rather obscure Choices le
;) ). Again, like the Diphthongs le, running it from a Filer window will
load the characters (provided Smart Quotes is running, of course).

   Clicking Refresh will re-scan the characters, in case you have changed
the denitions via the command line or by double-clicking on another Chars
le.

Diphthongs window
*****************

   Choosing Diphthongs... from the main menu will open the Diphthongs
window, containing a list of all the current diphthongs. The list is divided
into three columns, somewhat like this:

   First  Second  Subst
   -      -       
         -       
         -       
   f      i       
   f      l       

   The window uses an outline font (Trinity.Medium for the text,
Homerton.Bold for the heading, by default) so you can see exactly what is
going on.

   The First column contains the rst character in the sequence, the Second
column the second character, the Subst column the character that replaces
the two.

Using diphthongs
****************

   Most diphthongs in the list are fairly straightforward: f and i make , -
twice produces an en-dash (). There is however more than that to diphthongs:
you can combine several diphthongs. For instance, to get a longer em-dash,
type - three times: it will be substituted by an en-dash, and then by an
em-dash, as another diphthong was dened as  + - = . For when a diphthong
is substituted, it simulates a key-press, and can therefore be the rst part
of another diphthong. (Typing - yet again will turn the em-dash into a bullet
, as yet another diphthong was dened as  + - = ).

   Another example is fractions. 1 and / produce ; afterwards, typing
either 2 or 4 will get  or , as diphthongs have been dened for  and 2
and  and 4.

   Accents can also be provided: e and / results in , e and \ in , etc.
Circumexes are more difficult (you need a ^, which uses Shift), and umlauts
are downright difficult: " is already used, and using a colon is dangerous as
colons are commonly used after vowels. You could always use  or |.

   Cautionary tale: at one point I was going through the list of ligatures
in the character set, and found . Having just done , I added o + e = .
Then I typed does. Oops. So beware: dont add diphthongs just because
theres a character that *could* be substituted - you might not want to use
it. 

Known problems
**************

   If you are programming, typing commands at the CLI (F12 or taskwindow),
doing anything at all involving comms, or in general using an application
that doesnt look too kindly upon top-bit-set characters, turn Smart Quotes
substitution off (Adjust-click on the icon will do the trick temporarily).
Otherwise, the CLI will fail to recognise your command (file 'lters' not
found), any quotes or diphthongs will be tokenised if youre programming in
BASIC (its particularly spectacular in Zap ;) ), and any e-mail or usenet
postings will look particularly gruesome on some peoples machines. This
isnt a bug, or even a feature, so theres nothing you can do about it.

   As mentioned previously, Smart Quotes will often not substitute characters
when the cursor is in a writable icon  in a dialogue box or off a menu item,
for instance Name disc in the ADFS icon bar menu. This is because the WIMP
handles those key presses itself (unless the Notify option is set in the
validation string, e.g. KARTN), and Smart Quotes doesnt get a look in.
This shouldnt be too much of a problem  usually you dont want substitution
in those cases anyway. However, any applications that require you to enter
text in a dialogue box (a eld name in a database, for instance), will not
allow substitution.

   Those using Zap may nd certain diphthongs dont work  namely, those
using a shift-key to produce the second character, like A E  (if Caps Lock
is off), < <  etc. This is because, when Smart Quotes sends Zap a delete
character, Shift is still held down, so Zap looks at Shift-Delete and sees
the command DELETENEXT rather than DELETE, and so fails to delete the
character, so youre left with something like A, < etc. To get round this,
you have to change the key mappings:
      Edit the key mappings (iconbar menu, Options=>Edit keys)
      Find sDELETE in the le
      Replace whatever command is opposite it by DELETE
      Save the le
      Re-load the key mappings as the new one (Options=>Reload keys)
      
   On a similar level, if you hold down the hyphen key, you may nd that
dashes in various shapes and sizes start lining up, looking something like
this -------. (This was actually done in Edit as Zap is fast enough
not to have this problem ;) ). This is because Edit (or whoever the culprit
was) wasnt managing to delete characters fast enough before another one
comes along, so Smart Quotes fancy substitution method falls over. The
solution is simple: dont type as fast!

   If there is an error in the middle of the slimming down/fattening down
process, you may find that files are in the wrong place. Unless you know what
you're doing, copy your SQChoices directory to somewhere else, restore from
a backup, and copy the SQChoices directory back.

   As I don't have a CD-ROM or a network I haven't tested Smart Quotes
thoroughly on write-protected filing systems. If files haven't been copied,
Smart Quotes will re-create them when it next runs. If you want to keep them,
make a backup!

   I have been told of problems with certain terminal emulators (think it was
Hearsay), where Smart Quotes causes spurious interrupts or something. I dont
know any more about this, and knowing comms programs its probably not me ;).
But you have been warned.

   As mentioned elsewhere, KeyMouse uses Alt-Select to move a window.
Clicking Alt-Select on the iconbar makes it want to move the window 
obviously it cant, but tries all the same, and someone complains (ADFS
Filer on my machine). This isnt Smart Quotes fault!

   If windows appear in strange positions, or fail to appear at all when you
try and open them, you very probably have a corrupt Choices le. Delete it
and re-run the program; the program will complain that it cant nd a Choices
le, and will then create a new one with the default settings:
    All substitutions on
    Next double quote will be open, next single quote closed
    Use graphical settings box
    Show quote state in icon
    Use interactive help
    Kill module when quit
    Windows positioned to suit a mode 35 screen or similar (768x288)
   
   Impressions spell checker doesnt take kindly to  and  (certainly not
on my version, Publisher 4.01, ImpressionSpell 1.27). When spell checking, it
ignores  and , so if you spell check the word nding it will complain
that it doesnt know the word nding (rather than complain about not knowing
the word nding ;)). This is because, if you look at the character set
(double-click on Smart Quotes icon or run !Chars),  and  are buried among
the odds and ends, like bullets, fractions, dashes, etc., not among the
accents at all (Impression knows about accents - checking the word trange
will come up with trange and not trange). I suspect (I havent
tried it) Impression will ignore all characters from  to , and cope happily
with  to  (not  for some reason), so there will be the same problem for 
and  (but not for  and ).
   I dont know what you can do about this, apart from complaining to
Computer Concepts and using the Ignore button a lot ;)  the nice man from
Computer Concepts said they had no plans to add support for ligatures to
ImpressionSpell in the near future. (This is from the company whose own
literature, namely the DemoDoc le supplied with Publisher, recommends you
use ligatures all the time ;) ). If it bothers you, remove  and  from the
list.

How to contact me
*****************

All bug-reports, suggestions, comments or indeed any feedback at all will be
welcomed. Heres how to get to me:

E-mail     : 926286ki@udcf.gla.ac.uk during term-time
             These should be OK until June 1996
             At Christmas, Easter and during the summer, you can get me at
             wombat@altern.com, wombat@email.teaser.com or sam@altern.com, in order
             of preference (that is, if mail bounces off one of these or I dont
             answer within a week send to the next one).

Snail-mail : My term-time address, at least until June 1995, is:
             Sam Kington
             Flat 2/1
             44 Hotspur Street
             Glasgow G20 8NL
             SCOTLAND
             
             Again, a backup is the home address  anything that goes here will get
             to me eventually.
             Sam Kington
             Merlhiot
             24420 Savignac les Eglises
             FRANCE

Term-time is October to June, with bits off at Christmas (3 weeks) and
Easter (4 weeks).
