=========================================================================== [33mAMOK - Amiga Modula & Oberon Klub Standard Identifier for ProgInfo (Extract for Sourcecode)[31m =========================================================================== [4mHeader[0m All AMOK program must contain a header which incorporates all important information. All Modula-2 and Oberon programs must have a commentary in front of the keyword MODULE. It should be highlighted through "***" or "---" lines, but please don't frame it (the last "*" in the row is in the way). The header contains different entries, all beginning with ":"keyword".". If there is not enough space in a line then repeat the ":"keyword"." in the next line and continue with the entry. The exact syntax is important, since otherwise the program is not able to find the entries. The header must (!) contain at least the following entries: :Program. :Contents. :Author. :Copyright. :Language. :Translator. :History. If necessary add these items: :Support. :Imports. :Bugs. You can add these data voluntarily: :Address.

:Phone. :Update. :Remark. :Usage. Other entries, like date, shortcut, version shouldn't be used any more! Missing entries should be included or recontructed as soon as possible. [4mHints[0m There exists no formal determination for the header. But in order to have a single appearance you should obey the following rules. [4mEmpy entries[0m You can leave out some of the entries (except for the obligatory entries). Just leave out everything including the keyword. Empty entries can also contain only of spaces, asteriks "*" or dashes "-". Silly entries (e.g. ":Imports. nothing until now") should be omitted. [4m:Program.[0m Here you should enter the name of the program, which should be the same as the file name (with all extensions, e.g. "Test.def"). If the program name does not identify the program properly (e.g. altered Module "Strings"), you should add an annotation right after the name. [4m:Contents.[0m Short description of the program and its function. The description should be explanatory and must not be a long version of the program name (e.g. [33m[1mNOT :[0m[31m :Program. InOut.def :Contents. Definition modul Input/Output ). [4m:Author.[0m Please supply the full name. Pseudonyms are not valid. A program can also contain more than one author, e.g. if a PC-program was converted for the AMIGA. [4m:Address.[0m The address of the author is facultativ. It should contain street, number, post code, city and country. [4m:Phone.[0m The telefon number of the author including prefix. Additional information like reachable times are valid. If the program was written by more than one author (see above), so please submit the number of the author who can answer most of the questions. [4m:Copyright.[0m Here you can state if your program is Freeware or Shareware or if you release it Public Domain. Freeware: - the author determines the way of copying - keeps all rights of his program Shareware: - the author determines the way of copying - keeps all rights of his program and - you HAVE to pay a fee, if you use the program regularly (the Shareware fee). Annotations like "copy it, but leave my name in" are valid. For longer descriptions there should exist a link to another file. [4m:Language.[0m In most cases here will be written 'Modula-2' or 'Oberon'. If the program uses INLINE assembler code, then make a note. The same should be done, if the program does not use the modula standard. This applies e.g. if you use the type conversion of ADDRESS/BPTR in M2Amiga v3.2 or the dereferencing of BPTR pointers. The normal usage of the BPTR is excluded. The reason herefore is to warn people who want to use the program with other compilers. [4m:Translator.[0m Determines the compiler (/assembler/interpreter) and the version number (e.g. v1.17 or v2.0). It should be followed by compiler bugs, which are relevant for this program. [4m:History.[0m This is one of the most important entries. It contains information about the versions of the program, the dates, the author and the responsible person for the changes and an optional annotation. Example: :History. v1.1 [bne] 29-Mar-89 bug in Init() fixed There is an extra chapter for the version number. Corresponding definition and implementation modules should have always the same version number (revision number, brach number and key may be different). The date consists of the day (one or two digits), the month's shortcut (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec) (three letters) and the year (two or four digits). The author's name is submitted in brackets (members of the club use the shortcut). [4m:Support.[0m In order to be fair you should enter here all data about programs by other people where you have extracted ideas and bits & pieces. [4m:Imports.[0m If you import other modules than the standard ones, you have to include them here. If the program requires a special version then add the version number directly after the name. You can also create links to other AMOK disks. Example: :Imports. MemSystem1.3 [bne], List [mif] AMOK#7 [4m:Bugs.[0m Do you know about bugs in the module or are you not sure if the module is bugfree, then add a note here. If possible then describe the bugs as exact as possible (e.g. the faulty Procedure). If the module has not been bug tested completely then you should warn the others: ":Bugs. not tested". If you supply a ":Bugs. none" then you should be able to guarantee at least 99.9% correctness! [4m:Usage.[0m describes the syntax of a CLI-Command and its arguments. The usage should be described in EBNF or with a template (like in the DOS manual). [4mVersions numbers[0m The version number consists normally of two parts (version, revision), which are divided by a dot. The first fully running version should be called 1.0. Any change should be followed by an increase in the revision number with 1.9 < 1.10 < 1.11! If you have made major changes then increase the version number and set the revision number to 0. The version number is [33mNOT[31m a decimal, which is increased by 1/10. A revision is [33mNOT[31m a tenth of a version and a version does [33mNOT[31m contain 10 revisions! Version and revision are counted independently!!! Version 1.09 is not valid and 1.10 (first version, tenth revision) is between 1.9 and 1.11 and ist not the same as 1.1!! There exist no "hundreth" versions. If it is necessary to include an extra version in between then add an extra depth. Example: There exist all versions from 1.0 to 1.4 and somebody changes version 1.2. This version has got the number 1.2.1 (a branch version). You can display the version numbers as a tree: 1.0 | V 1.1 | V 1.2 | / \ / \ V V 1.3 1.2.1 | | V V 1.4 1.2.2 | etc. ... | V 1.9 | V 1.10 etc. This system is different from the one used by the Big Blue, but it is easier to understand, because it is quite clear, that 3.2 is the successor of 3.1 and not of 3.19. Versions and revisions can increase just as you like - Example: the libraries of the old 1.2 Workbench did have the version number 33.180 (33rd version, 180th revision). If you want to make it even more differentiated, then you can add letters. They are optional and don't tell anything about the order (e.g. 3.2d is the German and 3.2e is the English version). The idea by Bernd Preusing is now valid, where a implementation module can have a higher revision number than the corresponding definition module. So you don't have to change the definition module each time you make a small change and save a lot of work with Make. [4mSource code format[0m In order to keep your source code tidy (and Britain, of course, too), you should use the following format (it is not obligatory, but it should be [33measy[31m to read): * In each line there is only one logical command unit. * global procedures, variables and constants stand right at the beginning of the line. * Declarations and procedure bodies should be shifted right of the CONST, VAR, TYPE and PROCEDURE. * Parts of the programm, which are defined local or are in between certain constructs, should be shifted TWO letters to the right. * Corresponding BEGIN and END, IF, ELSE and END etc. should always be placed beneath each other. If there are more than 25 lines (one screen) between END and BEGIN etc. then add a remark after the END and say what has ended there. * Except for VAR, CONST, TYPE, BEGIN, DO, THEN, LOOP, RETURN and EXIT there is always a semikolon at the end of each line. * Elements of sets and RECORDs don't start with an capital letter, constants can start with either of both possibilities, everything else starts with capitals. Joint words may also have them in the middle (e.g. 'CapitalWords'). * If the parameter list does not fit in one line (75 characters) then put each parameter in a single line. * Imports are sorted alphabetically by their module names. If they are longer than two lines, then also the imported objects are sorted alphabetically. MODULE Example; CONST which = 106; PROCEDURE doSomething(this: Typ; VAR that: Art): BOOLEAN; CONST X = 1; Y = 10; VAR counter : INTEGER; BEGIN FOR counter := X TO Y DO Action(this, that); END RETURN that = which END doSomething; BEGIN IF doSomething(something, somethingElse) THEN Aktion1; ELSE Aktion2; END; END Example.