BCI NET 2/BCI NET 2.iso/archives/programming/source/chaos5_3src.lha/chaos/src/PORTING

Text File | 1994-01-27 | 5.2 KB | 145 lines

        Porting Chaos


1.) Source organization

  I have tried to write this program in a way to make porting easy.

  System independent stuff (being of general interest, except for some
  #ifdef AMIGA statements) is in the following files:
    Chaos.h
    DWZtabs.c
    Memory.c
    NonAmiga.h
    NonAmiga.c
    Out.c
    OutDWZ.c
    Pairings.c
    Players.c
    Project.c
    Rounds.c
    main.c
  The files are organized mainly due to the menus which are offered on
  the Amiga: A 'project' menu allowing things like loading, saving and
  quitting the program, a 'players' menu which is used to add or modify
  players, a rounds menu for the pairings and to enter results and a
  'output' menu.

  A special case are NonAmiga.h and NonAmiga.c: I used some Amiga
  functions in the system independent part, as they are of general use
  and easy to implement. BUT: I never tested this source! Handle it
  with care!

  DWZtabs.c contains tables which are used to compute the DWZ. (German
  rating number) This is very close to ELO or USCF, you might use it for
  another rating system. Please leave this and OutDWZ.c inside, as you
  might have german users. If you want to implement another rating
  system, please send the source to me, as I am very interested in
  including it into the Amiga version.

  The main pairing algorithm is in Pairings.c. It is (hopefully) well
  documented inside the file.



  System dependent stuff is in files ending with Ami:
    ARexxAmi.c
    MainAmi.c
    OutAmi.c
    PairingsAmi.c
    PlayersAmi.c
    ProjectAmi.c
    RoundsAmi.c
  In general xxxAmi.c implements the system dependent functions of xxx.c.
  (Examples: Opening a special window, receiving input from this window
  and so on.) You have to rewrite this from scratch. The advantage is,
  that you are *very* flexible in designing the user interface.

  You may ignore ARexxAmi.c: Rexx is a process communication language,
  which is used to control Chaos from the outside world on the Amiga.
  (I use this for example to update the rating numbers in a player
  database.)


  Note, that the program doesn't use strings directly! Chaos is a
  localized program, which means, that the user can select the language
  of the strings. (The Amigs supports this very well.) If you need a
  string, get it by calling GetChaosString(id), where id is a unique
  number. These numbers are defined in Chaos_Cat.h, the english strings
  (which are the default) themselves in Chaos_Cat.c. Additionally there
  are three functions present in Chaos_Cat.c:
    OpenChaosCatalog  - this is called at startup to select the
                language. (A so called catalog file is opened
                on the Amiga, if the language is anything else
                than english. The language might be selected
                by an option or something similar.)
    GetChaosString      - this returns a pointer to the string
    CloseChaosCatalog - the opponent to OpenChaosCatalog, called at
                exit.


2.) The documentation

  The documentation source is written in texinfo: This is a special set of
  tex macros and developed by the Free Software Foundation (the GNU
  project) especially for documentation purposes. I strongly encourage you,
  to read this documentation (as it might give you a feeling, how Chaos
  works on the Amiga) and to use it for your docs too, as it gives you the
  possibility to get three different documentation formats from on file:
    - Ascii format (by using the GNU program makeinfo)
    - DVI format (by using TeX), which can be brought into PostScript
    - Hypertext format, different versions available:
        GNU info    (created with makeinfo, read with GNU Emacs)
        www html    (World wide web, created with texi2html, read with
            Mosaic)
        AmigaGuide    (created with Amiga-makeinfo, read with
            Amiga-MultiView, probably not very useful for
            you... ;-)

  If you cannot get Makeinfo, ask me for the Ascii version or get it from
  the binary archive of the Amiga version.



3.) What you should do

  In general, I would like to see one big source archive finally, which
  can be compiled on any system by using the appropriate Makefile. This
  would make it easy to add enhancements (either for you or for me)
  or fix bugs in the general part. So try to come close to the following
  suggestions:

    - Do not change the general part (except for enhancements, of
      course). If you need to do, use something like

        #ifdef MSDOS
        ...
        #endif.

    - Create files called MainMac.c, RoundsMSDOS.c or PairingsCursesX.c
      (or OutCurses.c? Why not! ;-) which do the same as the respective
      xxxAmi.c files.

    - If possible, use the original documentation in texinfo format.
      Feel free to edit it, especially for introducing subsections
      on Amiga behaviour, Macintosh behaviour, ... whereever you want.

    - If you are ready, send the sources to me. I would like to get it
      through my compiler and update the source archive. Don't release
      your version, until you have my agreement. (This is really just
      to see, that it still works here.)

  Please understand, that I would like to keep it the same program on
  any system.

  One final note: Please be so kind and include into your program a
  possibility for the user to get informations (typically a menuitem
  called 'About' or something similar) and include a note there, that
  the original version is for the Amiga.




        Jochen Wiedmann, 26.01.1994