============================================================================ $VER: CNet ARexx Version Strings, v2.1 (10-Dec-94) by Dotoran! ============================================================================ The following text is taken "verbatim" from the Amiga Interface Style Guide concerning VERSION Strings: O \ / -----O---Cut-Here----------------------------------------------------------- / \ O AMIGA: User Interface Style Guide Commodore-Amiga, Incorporated Amiga Technical Reference Series Addison-Wesley Publishing Company, Inc. Copyright (c) 1991 by Commodore Electronics Limited Chapter Eight: The Shell, pages 110-111 EMBEDDED VERSION IDs Follow the standard method for indicating the version of your software. The Shell command VERSION provides support for version identification, but you have to follow a standard template. A text sequence that indicates the current version of your application should be embedded within your code. (It should also be put in your ARexx scripts and your configuration files.) The format of this text sequence is: $VER: . (..) The name of your application Major version number Minor version number Day created Numeric month created Year created If you follow this template, the user can find out what version of your software he is using with the Shell command VERSION. O \ / -----O---Cut-Here----------------------------------------------------------- / \ O I should also note that the use of the pronoun "he" is used only because the English Language does not have a genderless third pronoun. See PREFACE, "The Gender Question" on page V of the Style Guide for more information. Although the above is the "CBM Standard", I chose to slightly modify the Version Strings I use in MY creations, so as to make them more readable and easier to understand. To include a VERSION string that can be viewed using the VERSION command from a CLI, include this line somewhere near the beginning of your file: $VER: Name of Program, v???.??? (Day-Month-Year) by Author Text@ The closer this line appears to the BEGINNING of your file, the quicker the VERSION command will be able to find and display it on the screen. The first five characters should ALWAYS be: "$VER: " (minus the quotes) The V, E, and R should be CAPITAL letters, and you MUST include the SPACE after the colon(:), else the first character of your program's name will be chopped off. (Newer versions of the VERSION command do not have this problem, however it is still good practice to include the space). You should then print the NAME of your Program. You can use UPPER, lower, or Mixed Case. Next, for aesthetic purposes, I like to include a COMMA and SPACE before the version number. (This is not mentioned in the style guide, but makes for a nicer looking string). Finally, include the version number of your program. (Using the "v" is another aesthetic inclusion I like to use, although it is NOT necessary, and is NOT mentioned in the Style Guide.) Something I have come across in my investigations of the $VER: usage is that the VERSION command will STOP reading characters when it comes across the first SPACE found AFTER your period. It is for this reason that I told you to include the NAME of your program BEFORE the version number. (Again, this problem only seems to occur with older versions of the VERSION command). I'd also like to mention a bit about the REVISION NUMBER you choose to use. Although I like to use LETTERS after version numbers, like v6.3a or v6.3c, this is NOT the CBM Standard. Numbers following the period should be treated in incremental steps. Version 1.1 is NOT the same as version 1.10. The first is version "one-point-one", while the second is "one-point-ten". I'd like to explain a bit how MY numbering system works. It will be up to YOU to decide which method you choose to use. My system includes three elements: . If a file is completely rewritten from scratch, or has more than doubled in size, then it merits a MAJOR increment by me. If errors or new additions are made to more than one subroutine within the file, it merits a MINOR increment by me. [which is specified as a letter of the alphabet by me] is used if a small bug has been fixed. Generally, if no more than 2-3 lines of code need to be changed, it merits a FIX increment. Again, although I chose to deter from "standards", I believe this method more easily reflects how a file has evolved over the course of time. $VER: Name of Program, v???.??? (Day-Month-Year) by Author Text@ The VERSION command can also take an optional argument "FULL", which can be used to display even MORE version information, which is often times the DATE and AUTHOR's name. To add this additional information, follow the last character of your version number above with a SPACE, then the DATE of your program's inception. When writing for CNet Amiga, it is standard to create the date in this format: (DD-MMM-YY) Start with an Open Parenthesis, followed by the DAY NUMBER, as it would appear on a calendar(example: use 6, instead of 06, etc). Next type a hyphen, followed by the first three letters of the month, first letter capitalized. Type another hyphen, the last two digits of the year, and finish with a close parenthesis character. Again, you can use any date format you wish, but this is generally the accepted CNet Amiga format, but does NOT follow Commodore's Standard. I chose to use the above technique to avoid problems dealing with which digit represented the MONTH and which represented the DAY. After the date string, I like to include " by " (minus the quotes) and then follow this with whatever Author Text you wish to use. Generally, use the author text that will associate you to the work as closely as possible. By this, I mean if you write software under an alias or handle, like I do, then it would probably be better to use your ALIAS or HANDLE, instead of using your Real Name, etc. Lastly, NONE of this information was specified as being "standard" by Commodore, but it doesn't pose a problem for the VERSION command, so you might as well plug yourself as being the AUTHOR! Finally, depending on WHERE you place your VERSION string, you may need to use this little trick if you will be using some other text characters directly AFTER the VERSION text, but which should NOT be TREATED as VERSION text(example: if you placed the version string inside a Box of *'s, etc.) The "trick" is to TERMINATE your Version String with a Hex "00"x. Most text editors have a feature that allow you to insert Hex Characters. I use the AZ editor myself, which uses the RAMIGA-H key-combo to present a little requestor asking for the HEX DIGITS. You want to use "00" (minus the quotes) to enter this special character. In most editors, this character will appear to look exactly like a SPACE, but it ISN'T. If using AZ, check the status line at the top of your AZ window. You'll notice SPACES appear as "0x20"'s, while this special HEX character appears as a "0x00". CED - RAMIGA - (dash) Enter an Ascii "0" value. Looks like a REVERSE @ Symbol. Also note that in CED, this character looks to act as a LINEFEED, in that all characters appearing to the RIGHT of this character will appear on the next line in CED (Even though they ACTUALLY still exist on the SAME line) EDGE - In "Edit" Menu, "Enter Ascii..." Enter "0" value. Looks like a SPACE. ED & EMACS(MEMACS) - Do not have built-in functions to do this. :-( Finally, if you use one of those ARexx Compactor programs, you will have to create your VERSION String as a variable initialization, like this: version="$VER: Program Name, v???.??? (DD-MMM-YY) by Author@" The @ symbol is a HEX "00"x character, so that the final " isn't printed when using the "FULL" keyword with VERSION. You can use whatever variable name you wish to, as this means nothing. It will simply make sure your ARexx Compactor doesn't REMOVE the VERSION text, if it happens to appear in a text comment. The only comment that MUST appear in an ARexx Program is the first line of the program, and some Compactor's like to replace this with the shortest possible comment: /**/ options results ...etc... By using a variable initialization, you're "tricking" the Compactor into thinking this variable is needed(well, YES, it IS needed), so it will LEAVE IT ALONE, whereas if you included it in your initial COMMENT lines, it may have been stripped out by the Compactor. Here are four correctly formatted strings, using Commodore's standards: $VER: CNet Tool Kit 2.0 (1.8.94) $VER: Wheel of Fortune 6.31 (13.1.94) $VER: CNet Amiga 3.04 (30.1.94) $VER: Release 1.234 (1.8.75) Here they are again, except this time using MY version standards: $VER: CNet Tool Kit, v2.0 (1-Aug-94) by Dotoran & PMK! $VER: Wheel of Fortune, v6.3a (13-Jan-94) by Dotoran $VER: CNet Amiga, v3.04 (30-Jan-94) Perspective Software $VER: Release 1.2.34 (1-Aug-75) BETA These four strings(in MY standard) each contain an error: $VER:Hangman, v1.0 (23-Sep-91) by Dirty Dan $Ver: Battle Ship v1.2 (10-Jun-92) OMEGA GRAPHICS $VER: v3.0 BBS-Stats (25-Oct-93) by Dotoran $VER: CNet Amiga, v3.0 PRO (30-Jan-94) Ken Pletzer Can you see the mistakes in the above four strings? There's a missing space between colon and name in the first one. In the second example, the "er" is not capitalized. Only "v3.0" will be printed in the third example, and the "PRO" will not be printed in the last example. The last two mistakes occur when using VERSION alone, without the "FULL" keyword. After corrections are made, the above strings might look like these: $VER: Hangman, v1.0 (23-Sep-91) by Dirty Dan $VER: Battle Ship v1.2 (10-Jun-92) OMEGA GRAPHICS $VER: BBS-Stats, v3.0 (25-Oct-93) by Dotoran $VER: CNet Amiga PRO, v3.0 (30-Jan-94) Ken Pletzer And if they followed Commodore's standards, they'd look like these: $VER: Hangman 1.0 (23.9.91) $VER: Battle Ship 1.2 (10.6.92) $VER: BBS-Stats 3.0 (25.10.93) $VER: CNet Amiga PRO 3.0 (30.1.94) If you happen to mistakenly include TWO or more version strings in any program(or text file), then the FIRST ONE FOUND will be used. This is yet another reason to always include it somewhere in the beginning of the file. You'll then KNOW if you ever HAD a version string if you were to ever update the file. Let's try the VERSION command on this TEXT file. Type this command from a CLI prompt: >version CNet_ARexx_VStrings CNet ARexx Version Strings, v2.1 >version CNet_ARexx_VStrings FULL CNet ARexx Version Strings, v2.1 (10-Dec-94) by Dotoran! YES, you CAN include version strings in TEXT files. It does NOT have to be an ARexx Program File! And that's all there is to adding your own version strings to your ARexx files. Please try and include a version string in any files you write, as it will help those that use the file if they ever need to ask a question about it, or if they're planning on updating versions. ============================================================================ Frontiers BBS (716)/823-9892! ============================================================================