Font_ApplyFields problem

[Jonathan Coxhead]

   On 7 Nov 2001, at 10:43, Tony van der Hoff wrote:

> On 6 Nov 2001, in message <3BE7D1ED.25316.421216 at localhost>,
> "Jonathan Coxhead" <jonathan at doves.demon.co.uk> wrote:
> 
> [snip]
> 
> > 
> >    How about the following as plan of action:
> > 
> >       ---introduce a new typedef byte os_fb, to match os_fw.
> >       ---rename all the byte-wide functions (in the SWI files) as
> >          osfile_save_stamped_b() etc
> > 
> >    This appears to be a retrograde step so far. Now we have 2 completely 
> > parallel sets of functions, one set dealing in os_fw and ending in _w(),
> > one  set dealing in os_fb and ending in _b().
> > 
> That was indeed my original idea (which was based on Kevin's). Unless I've
> misunderstood your intentions, it has a fatal flaw, which, ironically, lies at
> the root of this entire debate :-).
> 
> In order to retain the binary compatibility with current OSLibs, the library
> *must* retain the short symbols, and associate them with the 8-bit system. Only
> in this way can the linker resolve by default, say, xosfile_save_stamped to an
> 8-bit function. So, as far as the library is concerned, OS_F stays 8-bit for
> ever, as do the associated functions. There is, therefore very little point in
> defining OS_FB (or OS_F8 as in Kevin's proposal).

   Ah, yes.

   The rest of the plan sounds fine, with 1 caveat.

> > > 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. 
> > 
> >    This is an *excellent* idea---much better than my "osf32.h". We could
> > use it  slightly differently though.
> > 
> >    Suppose osfile.swi contained "NEEDS osfile32", and we supply a header 
> > osfile32.h as follows:
> > 
> >       #ifndef osfile32_H
> >       #define osfile32_H
> > 
> >       #if !defined OSLIB_F8
> >       #define os_f                 os_fw
> >       #define xosfile_save_stamped xosfile_save_stamped_w
> >       #define osfile_save_stamped  osfile_save_stamped_w
> >       ... etc ...
> >       #else
> >       #define os_f                 os_fb
> >       #define xosfile_save_stamped xosfile_save_stamped_b
> >       #define osfile_save_stamped  osfile_save_stamped_b
> >       ... etc ...
> >       #endif
> > 
> >       #endif
> > 
> >    This makes the switch clearer, and more symmetrical. If you desperately
> > need  to call an 8- (_b) or 32-bit (_w) version explicitly, you can; you
> > get 32 bits  by default, using short names; and you can still switch to 8 bits
> > by adding a -DOSLIB_F8 to your command line.
> > 
> Indeed, I had already written an almost identical piece of code, until I
> realised its flaw. OK, it's cleaner, and symmetrical. However, as you say
> yourself, users won't see it, so elegance is IMHO relatively unimportant. I
> don't really see what it gains us.
> 
> >    There would be one file like the above for each SWI file that used os_f
> > file  handles (colourtrans32.h, devicefs32.h, etc). The typical OSLib user
> > would  never see them though: they are included automatically.
> > 
> OK, I have no problem with this, but what is its advantage over the single
> osf32.h? Arguably more elegant in one way, as it localises the macros, but
> more messy for maintenance. In particular, os_f would have to be #defined
> in each of the headers, or each xxx_32.h would have to #include a
> definition. As the user doesn't see it, I'd argue on favour of lower
> maintenance. However, I'm probably splitting hairs now.

   The basic requirement of any solution is that headers can never be allowed 
to include themselves, either directly or indirectly. The way the C type system 
works, you can get away with this sometimes; but it's a very bad idea. I read 
an excellent book on software (Lakos, _Large_Scale_C++_Software_Design_) which 
makes this point well.

   In abstract terms, this means that if you write a directed graph, where the 
"nodes" are the headers and the "arcs" point from a file to everything it 
includes, the graph must be acyclic.

   If we have a single "osf32.h" that is automatically included by OSLib 
headers, we can get the following

      os.h includes osf32.h
      osf32.h includes osfile.h
      osfile.h includes os.h

   (My way didn't have this particular flaw, because I was imagining that 
osf32.h would not be included by any other OSLib header---only by users.)

   But if each header xxx.h has its own associated xxx32.h, which it drags in 
automatically (but doesn't include anything else) then the formal problem goes 
away.

   This also has the benefit that when someone introduces a new header, which 
may need os_f/os_fw switching (assuming they want to do it like that), there is 
no central "repository" file that must be updated: they just create their own, 
independently of the rest of the system. This matches the OSLib design, where 
message numbers, error numbers, etc, are defined by the modules that export 
them, not in a central place.

   I guess the "new way" of writing a SWI definition would be write only the 
version with os_fw (but giving it a name with no _w suffix), and ignore os_f 
completely.

> > > 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.
> > 
> >    Yep, though I'd use a shorter name---OS is present twice, USE is kinda 
> > redeundant, giving OSLIB_F8.
> > 
> Yes, much better.
> 
> > > 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?
> > 
> >    Yayy!!
> > 
> Oh, goody - a consensus. :-)
> 
> > > There are a couple of aspects to this which need further consideration.
> > > Firstly, something similar needs to be done for assembler headers,
> > 
> >    The same idea should work for those---OSFile32.Hdr, etc, with symbol 
> > definitions for OSFile_SaveStamped in terms of OSFile_SaveStampedW etc.
> > 
> Yes, I agree; no real problem.
> 
> > > 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.
> > 
> >    It shouldn't be in types.h, because logically types.h is at the "bottom"
> > of  the call graph. It's important not to build-in cyclic dependencies
> > between  components. But you are right that distribution isn't a problem:
> > there's also  macros.h, remember. The new files are just more of the
> > same---the release  script would have to be modified to know about them, and
> > copy them to the  release directory, as it does types.h and macros.h at
> > present.
> > 
> Yes, again, no problem.
> 
> >    So, I think we're really getting somewhere here. What do you think of
> > that?
> > 
> I think we should go for it like this:
> 
> 1. OS_F, etc stays 8-bit for binary compatibility.
> 
> 2. single branch only in the conditional
> 
> 3. use OSLIB_F8 for the switch
> 
> 4. a single osf32.h file called by a NEEDS in the appropriate SWI files and
> located alongside h.types 

   So, this needs to be a different xxx32.h for each xxx.h.
> 
> 5. produce a similar OSF32.HDR file for assembler and locate it alongside
> HDR.TYPES

   Similarly here.

> 6. Amend the release scripts to include the new files.
> 
> 7. Slip the planned release date for V6.3 by a couple of weeks :-)
> 
> What have I forgotten?
> 
> >    PS: If we make this change, one vital thing must not be forgotten:
> > change  the symbol in ByteWide from os_f to os_fb, as well. Or we'll end up
> > with some  very serious errors!
> > 
> And we can't do that!

   Well, looks like we won't need to :-)

        /|
 o o o (_|/
        /|
       (_/