GENTUT99.TXT General Tutorial for Lisa GJ2 Fic3 -- the f3 language explained as a series of tiny essays Written by Aristo Tacoma with L.A.H. Date: 2011:2:29 Copyright author, further distribution license is www.yoga4d.org/cfdl.txt. Kids: there are other tutorials for you. But you should find pieces here and there which are easy to read. In B9, use the search function, CTR-F or F4 within each. ***ORGANISING YOUR FILES DURING YOUR WORK DOSBOX, at any rate in its present form, appreciates your commands without a question -- also when it involves overwriting files, even when you do REN or rename. For that reason, do DIR -- listing files -- very precisely and without thinking twice about it ALL THE TIME before you do such as REN, COPY or other commands as listed here. Inside DOSBOX, uppercase and lowercase doesn't make a difference, usually. This is consistent with how filenames are handled inside F3 in such a context. Normally, all active files that you work with are in the main folder, which technically inside DOSBOX is written this way: C:\BOEHM\BOEHMIAN When in F3 you don't specify a folder at all, this is the folder that is referred to. Only in some contexts does it make sense to specify a folder, and then usually it will be in order to bundle a bunch of something such as image files or LIGHT3D matrices with their virtual sculptures all together, so that there is no conflict with other such bunches in terms of filenames. However when MAKING each such file, you keep it in the Boehmian main folder. When done, you get it over to a subfolder using perhaps such a Dosbox command as we will give here, and then you can -- inside a program which opens up these -- refer also to the subfolder. Note that inside F3, you normally use forwardslash / instead of backslash \ when referring to such subfolders. In particular, if you have a bunch of something in MYBUNCH1 and you want to refer to IMAGE6.GJP inside this, you can write it as MYBUNCH1/IMAGE6.GJP. However to see whether that file exists, with some date info, around F3 inside the Dosbox, you write DIR MYBUNCH1\IMAGE6.GJP Such a command, when issued from C:\BOEHM\BOEHMIAN, will then refer to C:\BOEHM\BOEHMIAN\MYBUNCH1. Divided into two lines, you can write CD MYBUNCH1 DIR IMAGE6.GJP After this, you can do other operations such as COPY or DEL (delete) or REN (rename) and then, in order to start F3 again, get back to the main folder by going one step higher in the hierarchy of folders by typing CD .. Technically, the two dots refer to one step higher up, while it is possible to refer to a file in the present folder -- e.g. IMAGE3.GJP either as just that, IMAGE3.GJP, or by means of using the single dot, in a phrase like ./IMAGE3.GJP. The value of knowing this is that in case a program requires you to give a foldername and you do want to refer to the present folder, you can write a dot as a valid foldername (usually), or a dot followed by a slash, ./ when it is about getting a slash after the folder name. In order to see all files with suffix .TXT, which is required for all B9 edited files, and all program files when performed as programs, DIR *.TXT should do. When there are too many to be viewed comfortably, you can page the listing by the /WP command, as such DIR /WP which can include *.TXT or *.GJP or the like as this: DIR *.TXT /WP DIR *.GJP /WP this can also be used in connection with subfolders, DIR FOLDER6\*.GJP /WP or, without the 'wildcard' of the asterix, *, like DIR FOLDER6 /WP Note that a blank is required between such bits of the Dosbox phrases. To remove all content of a folder and also the folder itself, when you are SURE this is right, and all stuff that you ought to have backup of, you have backup, then: DEL TESTFOLD\*.* RMDIR TESTFOLD To make a new folder named TESTF5 MKDIR TESTF5 Note that * A folder cannot have same name as a file * RMDIR only works on empty folders, empty also in the sense of having no further subfolders in them. A convention is to have a suffix like .TXT or .GJP or, for backups, .BKP, .BK1, .BK2, .. .BK9, or for screen images, .BMP, after each file, but never after the name of a folder. A filename is ABCDEFGHIJKLMNOPQRSTUVWXYZ and maximum eight of them, prior to the (in principle optional) dot with three-letter suffix. Moderately and carefully used, one can also have hyphen _ and dash - inside the filename, and obviously the digits 0123456789. Never put a blank inside a filename, and don't experiment with other characters as it may cause a damage to the folder structure and so to other files. The DIR command can be used with the wildcard, and also the DEL command, but be very sure -- take a pause, breath, before you press ENTER when doing a DEL with wildcard, or you may have got to get a fresh Dosbox arrangement. To remove all files beginning with the letter Z and completing with .BKP do first view them so that you see nothing more than what you intend to remove is included, here: DIR Z*.BKP /WP DEL Z*.BKP In the same vein, before changing name of a file, do a DIR because it does a delete. Change name of a file without using a wildcard. Changing names of very many files will then usually take quite a lot of time so get the filenames thought through before you make many. DIR NEWNAME.* REN OLDNAME.TXT NEWNAME.TXT This shows all files, if any, which has name NEWNAME before any suffix like .TXT or .GJP or .BMP. LIGHT3D matrix files are among those who store with the .TXT extension, by the way. Then the OLDNAME.TXT file changes name to NEWNAME.TXT, and OLDNAME.TXT refers to nothing. Note that if you want to view a matrix file -- which can be valuable for program correction -- it consists of numbers -- each on one line and possibly very many more lines than B9 is set up to handle, but quite short such lines. This can then be viewed, page by page, if you go into F3 and type this: :FILENAME.TXT MORE When you are working on a program, and you are fixing this, improving that, and so forth, and so on, if you follow, note that sometimes a valuable improvement of a program is added after a not valuable 'fixing' of a function occurred. You may want to be able to go back a number of backups, in a programming session, even a day or two back, to recover the 'unfixed' program. So, imagine that on day one, you do COPY regularly, as follows, of MYPROG1.TXT, between working on it: COPY MYPROG1.TXT MYPROG1.BK1 ..work on it in B9, and testing.. COPY MYPROG1.TXT MYPROG1.BK2 ..more such work.. . . COPY MYPROG1.TXT MYPROG.BK8 On day two, we imagine, you want to do more work, but you feel inclined to retain yesterday's backups. So: MKDIR BKPTEST1 COPY MYPROG1.* BKPTEST1 DEL MYPROG1.BK? The question-mark is a wildcard which works on one single character at a time only. It will here cover BK followed by any letter or digit or dash or hyphen. You will watch out when doing the DEL, so you don't automatically use the same phrase as you used in the line above with COPY. Don't do DEL carelessly. To recover then e.g. MYPROG1.BK4 be sure to give it a new name which doesn't overwrite the new good stuff you after all have added to MYPROG1.TXT. This new name ought to have the word TEST in it, as a convention that it is a highly temporary file, but it must have the suffix .TXT if you wish to copy in B9 with CTR-C .. CTR-C of some dozens of lines in it and do a CTR-V or paste into the proper MYPROG1.TXT file. So: COPY BKPTEST1\MYPROG1.BK5 REN MYPROG1.BK5 TEST5.TXT Note that COPY can be written without 'destination' as I just showed, when you copy from another folder into the present folder, and then only when you are sure that there is no file already name that which must be preserved. To get it over to the new name TEST5.TXT straight away, do COPY BKPTEST1\MYPROG1.BK5 TEST5.TXT By the way, after you make the BKPTEST1 folder and have content in it, check it by a DIR BKPTEST1 as a rule of thumb, just to be sure. To get away all TEST files, do DEL TEST*.* In all use of DEL, be careful with writing it precisely as it should be. Be twice careful when using the wildcard. You notice that the wildcard *.* on its own means 'all files in current folder', and so you must be sure ALWAYS to have NO BLANKS between a wildcard and the additional characters when indeed you want it to melt in meaning. A phrase like DEL *.* destroys the current folder so it must be re-made. When you have done with your work, you remove the folder used for backups. These exists a bit longer than TEST.. files, so BKP can be a useful convention to refer to these folders; besides, since it is good to keep filenames of a temporary kind like TEST.. different from foldernames when you use wildcards, don't begin, if I can point it out, most respectfully, foldernames with TEST. The phrase TEST is easy to use in such cases for temporary names as the letters are near each other on the keyboard, and can be clicked by one hand, in a fun and circular manner. Note that in Dosbox, arrow-up gives you access to earlier commands typed, so you can modify them by backspace and/or left-arrow. But don't do this in a sloppy way when it comes to DEL especially if it also has wildcards! Well, then, removing the BKPTEST1 would involve DEL BKPTEST1\*.* RMDIR BKPTEST1 If you do a CD .. so that you get higher up in the C:\BOEHM\BOEHMIAN Dosbox internal hierarchy than normal for F3 work, which is not normally a great idea, do a CD to get back again: CD \BOEHM\BOEHMIAN In such cases where it is called for that you have a connection to something other than the workbox of Dosbox and this connection is reflected in a letter such as D, followed by a colon, you can 'upload' to D: something of you work by a command like: COPY MYPROG1.TXT D: The best bet of getting a folder over from within Dosbox is to recreate it. In some cases the folder name can be the same as the filename without a suffix, but normally it should be a little bit different unless there are particular reasons for it. Imagine that it is MYPROG1F -- still not more than 8 characters as you see -- and you want it over to D: MKDIR D:MYPROG1F COPY MYPROG1F\*.* D:MYPROG1F In such cases as this D: has been set up to refer to something that you want to have into your working folder, and you have checked that there is no overlapping of names there, you can do something like this, if the names are APROG5 and APROG5F: MKDIR APROG5F COPY D:APROG5.* COPY D:APROG5F\*.* APROG5F If we imagine that the Dosbox is beneath the net, and that the net is mounted to D: somehow, then copying to it can be called uploading, and copying from it can be called downloading. This what we just did can then be called to download from the net. This is not done unless there is an arrangement in which the Dosbox is properly set up to activate the D: in just this way. D: is then not a fixed place on the disk, but rather enabled as needed, and used moderately. A hint when you use B9 and want to save a file to a new name: if uncertain, save to e.g. TEST5, -- with the convention that files named such are not for lasting storage and so this is a safe bet -- then leave B9 (press ESC), do the DIR you like, then REN TEST5.TXT into whatever is the new right good name. Remember that XO is the quick way to get from F3 in the text mode over to Dosbox when you do such commands. It is also recommended you do XO after small text-line actions in F3 and then restart F3 before doing bigger things in F3. Remember to keep the name of the main program in F3, as a convention, identical to the filename of the program. To check whether a short name like that is already in use by F3, start up F3, and in the text mode, simply type it in. You will get a message like HEAL THIS PLS if the name is unused, and then, if it sounds good and is appropriate, use it as name of your program. Note also that when you type a word this way, if the word does in fact have a function, it may be that this function is beginning to play itself off, so it is always good to have a regular look into documentation so you have a good general awareness of what names not to use. Note however that when you do define a new name which has a defintion at a higher level only, your definition will apply for all your work after the time of your definition. This also applies for AUTOSTART: the most recent definition is the name of the function which will start up the whole beautiful lovely program of yours ;) ***