=========================================================================== AMOK - Amiga Modula & Oberon Klub "Poster": Norm bzw. Standardform für AMOK-Beiträge Tips und Anhaltspunkte für Veröffentlichungen =========================================================================== Introduction AMOK welcomes also Modula-2 or Oberon programs, written by people other than the club members, on the AMOK disks. The aim of the PD series is to spread Modula & Oberon as far as possible. Since both languages support easy exchange of the program modules, every programmer can contribute something. The bigger the module library is, the easier it is to save time and work, since you don't have to 'invent the wheel a second time'. If you have written modules which you think that other might have use for them, then send them to AMOK. If it is possible, we will publish it in our AMOK series. We don't expect programs by genius', but if you want your program published, you should obey the rules below. Like this it is guaranteed that your program is really usefull. 1) Criteria As mentioned above we don't expect anything revolutionary, but the program should do what it is expected to do in a senseful and correct way. A simple but useful module has got more chances, than a great project, which does often crash! 2) AMOK demands The following are obligatory for all AMOK submissions: * Each module must be supported by documentation. Without documentation the modules are useless for others. There are the following possibilities for documentation on AMOK disks: - documentation in an extra file with the suffix ".dok" (the German documentation) or ".doc" (the English one) - short description of the procedures in the definition modul. This is all explained in 'HeaderInfo'. The documentation should at least contain the following information: - meaning and function of the parameter of the procedures - function and usage of the procedures - meaning and returning values of the procedures - important notes on exporting variables, constants and types - notes on bugs (if known) - information on limits or warnings If possible then write the documentation in pure ASCII code (so it can be used with MuchMore and 'copy to PRT:'). * Very important are also the files with the product information (".product-info") which are specificated after the FishROM Database Draft #5 (or higher, changes see below!). Without this the chance to get onto an AMOK disk is very low. A description of the file format is on disk (file 'Product-Info.Spec'). You should use English for description, but any other language is better than nothing. We have decided to use the .product-info format by Fred Fish. This has many advantages: - just ONE description for AMOK and Fish - KingFisher is able to administer AMOK disks - we can create the contents files automatically The format must be used as it is, but there are some changes from Draft #6 by Fred Fish: --> .reference is not optional for AMOK files. It must be supplied if there exists an earlier version in order to create a link to that version. Ex.: --------schnipp-------- .reference AMOK#99:DrawA5000/ 1.0 --------schnapp-------- Creates e.g. "Update to version 1.0 on AMOK #99" --> Source is not optional. This string is searched for the following keywords: Oberon, Modula, M2, Arexx. The keywords then appear directly after the name (in brackets). Ex.: DrawA5000 1.1 (Oberon/Modula/Arexx) --> We introduced a new field: .beschreibung This schould contain the description in german language. This field is used to generate the file 'Inhalt'. You can find examples on each AMOK disk (upto 103 only as 'mini-info', which was created by ourselves). * The modules should always have their source code with them. Like this other programmers are able to learn something from your program and it is then possible to remove some bugs or one is able to configure the program for one's needs. But there are some exceptions: - the program is really exceptional and should be patented (it must be totally bugfree) - the modules are part of a commercially distributed program and you don't want others to steal parts of it - your programming is so bad and your methods so abstruse, that you don't want to take the risk others seeing your source code (in this case you should think about changing to C or Assembler!) * Definition and implementation modules should contain our module header (see 'HeaderInfo'). This is necessary, since the AMOK library contains already some Megabyte. Please stick with the format in 'HeaderInfo'. * All files and directories should have icons, so that they are easily accessible from Workbench. The default tool for text files (source and documentation) should be ':c/MuchMore'. 3) AMOK conventions Please obey the following: * If you use non standard modules for compiling then you should supply them. Please take care that the sym-key is correct, i.e. everything is compiled with the same definition module. If there are more than one version of an imported module, then state the required one (:Imports.). * Please use only 70 to 75 characters in the source code and the documentation. MuchMore and M2Emacs accept up to 80 characters, but if you print the text, it is quite useful to have a little space on one margin. * Procedure, variables, constants and type names should be English. The same applies for the short descriptions of the procedures (see AMOK#7, ProgInfo/StandardIDs). You shouldn't mix English with other languages. * If have small demos, you can use them to easily demonstrate the functions of a module. In most cases are test modules or other examples already there, because they are 'side effects' of your actual program. * Please be fair about other programmers. PD does not mean that you can steal whatever you like. If you take parts from others, then mention the author in the module header or in remark lines. If you want to use them commercially you need a written permission of the author. And please don't forget the shareware fees. 4) Programming guidelines The following is not only important for AMOK disks, but should be dealt with by all programmers. If these information are not evident for you, then you should change your programms IMMEDIATELY! * All programs must be programmed according to the guidelines of the ROM Kernal Reference Manuals. - Amiga User Interface Style Guide ISBN 0-201-57757-7, Addison-Wesley - Amiga ROM Kernel Manual: Libraries ISBN 0-201-56774-1, Addison-Wesley - Amiga ROM Kernel Manual: Includes & Autodocs ISBN 0-201-56773-3, A.-W. - Amiga ROM Kernel Manual: Devices ISBN 0-201-56775-X, Addison-Wesley - Amiga Hardware Manual ISBN 0-201-56776-8, Addison-Wesley - The Amiga Guru Book, Ralph Babel, published by author - Native Developer's Update 3.1 (Examples, Debugging-Tools, Includes, Autodocs) * All programs must have an exit, i.e. you don't have to reboot the computer and everything should be in the same state as before starting the program. All devices and resources must be released (deallocation of memory, closure of windows, screens and files). * Programs shouldn't behave as if they were the only program in the system. They should take care of the multitasking and its restrictions (e.g. usage of devices and resources). * All programs should work logically and shouldn't fail with false entries. * Never expect to get all resources you need. Programs should always have a defined way of exit, if e.g. a file couldn't be opened or if there isn't enough memory left. * The user interface should be standard AMIGA one (see Amiga User Interface Style Guide). * The programs shouldn't rely on a certain device configuration (e.g. A500+ with 2 MB and 3 disk drives). * It is important for future library modules to make the procedures reentrant. Just in case it makes sense to use them from different tasks at the same time (in Modula it is not possible to import the same module twice). --- Have fun