Font_ApplyFields problem

[Tony van der Hoff]

On 5 Nov 2001, in message <3BE681BB.18540.DB3216 at localhost>,
"Jonathan Coxhead" <jonathan at doves.demon.co.uk> wrote:

>    On 5 Nov 2001, at 17:58, Tony van der Hoff wrote:
> 
> > "[file handle]. This is a small integer (typically going downwards from
> > 255), but must be treated as a 32-bit word for future compatibility.
> > [...] On exit, your filing system must return a 32-bit file handle that
> > it uses internally to [communicate with?] FileSwitch"
> 
>    This has been well-known for a long time---it's not new information, as
> far  as I'm concerned.
> 
Ah, well, I had it pointed out to me only relatively recently :-)

> > Based on this statement, in an admittedly obscure corner of the PRM, I am
> > moving towards the opinion that OSLib, if not bugged, certainly
> > disregards a PRM recommendation, and ought now to be fixed.
> 
>    But it has been fixed! All the functions anyone needs are there,
> together  with some older ones that may work only on older systems. There
> are *dozens* of  functions in OSLib that only work on older operating
> systems, but the  assumption is that OSLib may be used on any of them, so
> we keep on providing  all of them. As I have written before, if you don't
> use them, they do no harm.
> 
> > The simple fix would be to change the existing 8-bit functions to take
> > 16-bit
>   ^^ 32

Pedant! ;-)

[snip]
> 
>    You just want to give these people extra work. Why? "It's for their own 
> good"? Why not let them decide that?
> 
No, I have absolutely no desire to give anyone extra work, least of all
myself; that's an unfair and unfounded accusation. I also don't see myself as
a bully, as you well know. However, I don't like having potentially dangerous
bits of code in the library, which could easily be mistakenly used,
especially by novices, so I want to make it harder to make that mistake. 

This case is different from all the dozens of obsolete functions to which you
refer, in that, say, OSFile_SaveStamped is *not* obsolete in any version of
RISC OS, so neither should be the intuitive OSLib call osfile_save_stamped().
We have had to break your own naming conventions to introduce
osfile_save_stamped_w(), and I think we should at least try to return to the
status quo. Maybe you'll argue that these conventions are broken elsewhere,
but I don't believe that that's sufficient justification to perpetuate this
particular mismatch.

It should IMHO be the user's choice to use 8-bit handles, but default to 32
bits; not vice versa. I also happen to believe that it would be informative
to users to be aware that their code is not PRM-compliant, so that they can
choose to take appropriate action. Concealment of the truth is only another
form of bullying.

The users *have* been making their views known. It seems that those who care
on this list (arguably not a representative sample, but certainly a
knowledgable one) are pretty much unanimous in asking for a change. We, the
maintainers, are in fact currently guilty of bullying behaviour by denying
them their wishes.

The amount of extra work involved needs to be kept in perspective; for my
proposal it's an extra line in a makefile, for yours it's an extra line in
each source module. Both are trivial tasks, but I believe mine would win by a
small margin. However, by combining our ideas, I believe we can reduce even
this.

[snip]
> 
>    The question, is how can we make the upgrade path as easy as possible
> (so  everyone can do it conveniently) but *not* compulsory, as that's a
> form of  bullying. (A library should provided services, not enforce
> policy.)
> 
Indeed; but it should provide services which are PRM compliant. You may as
well accuse the PRM of bullying :-)

>    So here's my counterproposal: how about a new header file, called
> "osf32.h"  or similar, that maps *all* the "short" names to the form with
> W:
> 
>       #define os_f                 os_fw
>       #define xosfile_save_stamped xosfile_save_stamped_w
>       #define osfile_save_stamped  osfile_save_stamped_w
>       ... etc ...
> 
>    With this file, the only thing an application writer has to do to
> upgrade  from 8- to 32-bit file handles is
> 
>       #include "oslib/osf32.h"
> 
> at the begining of each source file. If they don't do this, they get the
> old  behaviour---binary (& source) compatible. If they do do it, they get
> the new  behaviour, which is not binary compatible, but (assuming they have
> used os_f  properly in all their source files) will still be consistent
> across the whole  application.
> 
>    I've attached the skeleton of such a file. As well as redefining the 
> symbols, it also checks that the various header files have not already been
> included---it would be an error to #include, say, "dosfs.h" before
> "osf32.h",  because the functions would then have incorrect 8-bit
> prototypes. Luckily,  "osf32.h" can check this, so it's completely "safe"
> from that point of view.  (It also has to make sure that it includes the
> files in the order of their  dependency, e g, arcweb.h after wimp.h. It
> does that too.)
> 
>    I don't see any way of making it easier than this, while still leaving
> the  application writer in control of their own code---which I'm strongly
> in favour  of!
> 

Excellent, that looks good, and is maybe not a mile away from my own
proposal. However, I have one criticism of this scheme: the default would be
an 8-bit system, and therefore, whilst it achieves the aim of restoring the
short symbols, it doesn't really promote (note: not compel) migration to a
32-bit system.

So, perhaps can we refine it like this:

1. Add a switch to your putative header file:
     # if !defined OSLIB_USE_OS_F8	
       #define os_f                 os_fw
       #define xosfile_save_stamped xosfile_save_stamped_w
       #define osfile_save_stamped  osfile_save_stamped_w
       ... etc ...
     #endif
     
2. Add a NEEDS osf32 to the appropriate SWI files to spare the user the
*extra work* of specifying his own #include. This also obviates the need for
the tests in osf32.h, with the consequent inconvenience (*extra work*) to the
user of a compile time error if the #includes are in the wrong order. 

3. Add a comment to the help text for OS_F and all the 8-bit functions,
telling the user to #define OSLIB_USE_OS_F8 if he really wants 8-bit handles.

Any user who needs 8-bit binary compatibility will get it by default; any
user (there can't be many) who opts for 8-bit source compatibility can set
the switch in his make file (surely that's minimal *extra work*); anyone else
gets PRM-compliant 32-bit handles. Everyone can use the short symbols, and
migrate from 8 to 32 bit by simply undefining a constant. Would that finally
satisfy everyone?

There are a couple of aspects to this which need further consideration.
Firstly, something similar needs to be done for assembler headers, and
secondly, how to ensure the distribution of osf32.h (all other headers, apart
from types.h, are regenerated on each build). I guess we could stick it
alongside types.h, or maybe it would be best to just add the code to types.h;
this would save the extra NEEDS.

-- 
Tony van der Hoff         | MailTo:tony at mk-net.demon.co.uk
                          | MailTo:avanderhoff at iee.org
Buckinghamshire, England  | http:www.mk-net.demon.co.uk