============================================================================== Quick HELP V1.2 © J.Tyberghein Sun Dec 10 16:44:25 1989 ============================================================================== Preface ------- These programs are intended for every (CLI-)user. They are extremely useful if you are, for example, a programmer and you have some help-files. Suppose that you want to know the syntax of the ARP Gads command. Normally you would start an editor (or use the one which is already in memory) and load the corresponding help-file. (You can of course 'type' them, but this can be very timeconsuming if the help-file is big) Then you must search the right entry in this help-file. This may look easy to you, but sometimes it's just difficult enough to refrain you from using such help-files. These three utilites (MakeHelp, Help and ArcFiles) allow you to make your own help-files. When this is done you simply type 'Help Gads' and there comes your information ! To guarantee maximum flexibility these programs are able to read files crunched with the PowerPacker (Author Nico François). You can crunch each help-file individually and then archive them in one big file. The advantage of this is that the resulting file will be smaller than the sum of the original files (although a bit bigger than if you had crunched them all together), but it will only be necessary to decrunch the individual files when needed (of course this will be done automatically for you). To guarantee an even greater amount of flexibility you can show the information you want in every editor you like. (The ouput will be put in a temporary file and the editor will automatically be invoked with this file) And in case you have PPMore (also by Nico François), the biggest amount of flexibility is likely to be yours. For in that case there is no additional overhead for using a temporary file. These programs (Help, MakeHelp and ArcFiles V1.2) are shareware. If you like and/or use these programs a lot I would appreciate it very much if you'd send me a contribution of $10 US ($15 if you want to get a new update (when one is available)). Please send money by international money order, EuroCheck (in Belgian Francs (BF) !) or cash, because it's very difficult for me to cash in other checks. If you want an update please state your current version. If you want to use any of these programs for commercial purposes please write for permission ! If you have any suggestions or remarks you can write to (Bug reports are welcome too) Jorrit Tyberghein Hepmansbossen 31 3990 Meerhout BELGIUM WARNING: If you want to use this utilities you must have Arp 1.3 or later. If you want to use the MEMORY option with PPMore (explained later) you need PPMore version 1.3 or later. These programs accept crunched DATA-files made by PowerPacker 1.1 or later. Only use Help, MakeHelp and ArcFiles if they have the same version number (unless stated otherwise). If you use the PROG option (in HELP), you must assign T:. At the end of this document you find a global example. ArcFiles -------- +---------------------------------------------+ | Commandline template: | | Files/...,TO=ARC/a,ADD/s,LIST/s: | |---------------------------------------------| | Usage: | | ArcFiles { ... } [ADD] | | or | | ArcFiles LIST | +---------------------------------------------+ This program is a small archiver. It is made especially for the help utilities. You can use it for your own purposes if you like (but not commercially). At the moment it is not possible to extract files. This will of course be possible in future releases. : files to archive you can use all arp wildcards (see the arp documentation for more information) : this is the destination for the archive ADD : if this option is used the will be appended to an existing archive LIST : generate a listing of this archive if this option is specified must be an existing archive file examples: ArcFiles dh0:docs/*.docs to dh0:DocArc.ppa will archive all files in 'dh0:docs' with extension '.docs' in the file 'dh0:DocArc.ppa'. If this destination file was there already it will be deleted. ArcFiles dh0:docs/*.docs to dh0:DocArc.ppa add will add the files in 'dh0:docs' with extension '.docs' to the existing archive file dh0:DocArc.ppa ArcFiles arc dh0:DocArc.ppa list will generate a listing of all the files in 'dh0:DocArc.ppa'. ArcFiles dh0:docs/Arp.doc df0:sources/*.c to df0:ArpAndSources.ppa will archive the file 'dh0:docs/Arp.doc' and all files in 'df0:sources' with extension '.c' in 'df0:ArpAndSources.ppa'. Note that ArcFiles will give no warning if 'dh0:docs/Arp.doc' does not exist. It will simply not archive it (rather obvious isn't it ?). Arc format (V1.2): I will give a description of the Arc format, so you can use it for your own purposes. The file starts with two longwords. The first is equal to 'PPA1'. The second is the offset in the file to where the Archive descriptor table is located. After these two longwords the files begin. The archive descriptor (at the end of the file) contains the following: A null terminated string : the name and path name of the sub-file A long word indicating the offset of the sub-file in this archive A long word indicating the length of the sub-file And this is repeated for every sub-file in the archive. Simply check for EOF to stop scanning. MakeHelp -------- +---------------------------------------------+ | Commandline template: | | From,CtrlFile,ADD/s,WORD/k,CLASS/k: | |---------------------------------------------| | Usage: | | MakeHelp [ADD] | | [WORD num] [CLASS class] | +---------------------------------------------+ This program makes the help control files for you. These control files are plain ASCII so you can add or delete lines as you wish. : the file containing the help (in a special format, explained below) : the control file to make or to adjust ADD : specify this option if you want to add help items to the control file (adjusting) WORD num : normally the parser searches for the first word in the text. This word will be the keyword for you to use with the help utility (see below for an example). With this option you can specify which word you want as the keyword CLASS class : to make the Quick Help utilities more flexible, you can group your help items in classes. When you use this option the newly added help items will be of class . If you omit this option they will have class 'Misc' (from miscellaneous). The help-file must have the following format: If the help-file is a crunched or normal file: When you place a marker ('@') in the beginning of a line, MakeHelp will search for the next (depending on the WORD option) word and will start a new help item entry here. This word is then the keyword for the Help utility. This marker is not necessary in the beginning of the file. At the end of the help text for this item you place '===' in the beginning of the line. This is not necessary at the end of the file. If the help-file is an archive (each individual file may be crunched): If each individual file in the help-file corresponds with one help item, you need not place markers. The items are selected automatically. In fact you can think about each individual file as a real file. With this in your mind you can reread the previous paragraph. If there are multiple help items in each individual file you must place the corresponding markers (read the previous paragraph for for more information) examples: MakeHelp dh0:docs/arp.ppa s:help.file will make a new file 's:help.file' and add all marked help items in the archive file 'dh0:docs/arp.ppa'. If every individual file in the archive corresponds with one help-item, no markers are needed. MakeHelp dh0:docs/arexx.doc s:help.file add will add all marked help items in the normal file 'dh0:docs/arexx.doc' to 's:help.file'. The file 's:help.file' must already exist. MakeHelp dh0:docs/arexx.doc s:help.file add word 2 same as previous but we now take the second word after the marker '@' as our keyword. MakeHelp dh0:docs/arp.ppa s:help.file class arp same as the first example, but now the items will have class 'arp' in stead of 'Misc'. Control file format (V1.2): There are two possible lines in a control file: an option line or a normal line. - An option line starts with '#'. The following options are supported: PROG prog When Help selects a help item after this option, the help text will be directed to the program 'prog' (most likely an editor). While prog is executing you can find the help text in the file t:HelpTemp. MEMORY prog Same as previous option, but now there is no temporary file needed. The help text is loaded directly in memory. At the moment only PPMore (version 1.3) supports this option (MEMORY PPMore), but you can write your own programs to support this option if you like. You could, for example, use this option to make an efficient ARexx interface. When prog is executed it will have the following argument line: -@,,, The first three hex integers are all longwords. If the first bit (bit 0) of the last hex integer (Hex options) is 1, you must free the memory when you are ready (With Help this is always the case). for example: -@C02310,12C0,1,Title must be interpreted as: on address 0xC02310 you find my text. It is 0x12C0 bytes long and you must free it after you are ready. The title is 'Title'. RUN Use this option if you want to run <prog> (from MEMORY or PROG) instead of executing. (executing is the default) NORUN Use this option if you want to execute <prog>. (default) STDO When this option is used, the help text will go to the standard Output (the CLI window). This option overrides PROG and MEMORY and is the default. CLASS <class> All following help items will be of class <class>. FILE <file> Default file for help text (explained below). - All other lines are help item lines. They have the following format: <KeyWord> '|' <File> or '*' '|' <Offset> [ '|' <individual file> ] <KeyWord> is obvious. <File> is the file where the help text can be found. If <File> is a '*' the current file is taken (FILE option). <Offset> is the offset in the file where the help text starts if the file is not archived, and the offset in the individual file if the file is archived. <individual file> (only for archived files) is the individual file where the help text can be found. This control file format implies that: - If you change the help-file you must change the control file, because some offsets could change. - If you add individual files to the help-file (an archive file in this case) you need not change the offsets because the offsets are relative in the individual files, and you only add another individual file. - If a help-file is not an archive you may freely crunch or decrunch this file (with PowerPacker), because the offsets will not change (the offsets are always the offsets in the decrunched file). - Crunched archive files are not supported (and not very useful). - If you rename the help-file, you must change the corresponding FILE option in the control file. Help ---- +---------------------------------------------------------+ | Commandline template: | | Name/a,CtrlFile,RUN/s,NORUN/s,MEMORY/k,PROG/k,STDO/s: | |---------------------------------------------------------| | Usage: | | Help [<Class>,]<Name> [<File>] [RUN | NORUN] | | [STDO | (MEMORY | PROG) prog] | +---------------------------------------------------------+ This utility gives you the help you want. <Name> : this is the help item you want help about You will get the first corresponding help item HELP finds. Note that it is not necessary to give the full help item name. Case is not important either. <Class> : if <Class> is specified HELP will look for the help item in this Class. Note that it is not necessary to give the full class name. Case is not important. <File> : control file (made by MakeHelp). 's:help.file' is the default. RUN NORUN STDO MEMORY PROG RUN : these options are the same as the equivalent options in the control file. When one of these options is given, the corresponding control file options are ignored. examples: Help Gads gives help about the ARP function 'Gads' (if your help-files and control file are correct) Help NewArp,Gads will give help about the ARP function 'Gads' in class 'NewArp'. (class 'NewArp' could for example contain all additions to the 'Gads' function in 1.3) Help Gads run memory ppmore gives help about 'Gads'. HELP will run 'PPMore'. Because we used the 'memory' option, there will be no temporary file. Note that you can only use the 'memory' option if you have PPMore 1.3 or later. Global example -------------- Suppose that I have 3 help-files, each one containing 2 help items. Helpfile1: | command list | ... (help for list command) | command dir | ... (help for dir command) Helpfile2: | command copy | ... (help for copy) | move | ... (help for move) Helpfile3: | command delete | ... (help for delete) | command format | ... (help for format) Fine,... I notice that each help item (like 'list','dir','copy',...) is the second word, but I didn't realize this wasn't the case with 'move' ! I must add marks to the help-files because every help-file contains 2 help items. Helpfile1: | @command list | ... (help for list command) | === | @command dir | ... (help for dir command) | === Helpfile2: | @command copy | ... (help for copy) | === | @move | ... (help for move) | === Helpfile3: | @command delete | ... (help for delete) | === | @command format | ... (help for format) | === (Strange, I still didn't see that 'move' is not the second word !) First I am going to crunch all help-files with the PowerPacker CLI command. So I type: 1> crunch HelpFile* ram: All my help-files are on the ram disk. 1> dir ram: | t (dir) | helpfile1.pp helpfile2.pp | helpfile3.pp Now I archive them. 1> arcfiles ram:* to ram:HelpFiles.ppa 1> delete ram:*.pp 1> dir ram: | t (dir) | HelpFiles.ppa Everything is going fine. Let's make a control file. 1> makehelp ram:HelpFiles.ppa s:Help.File word 2 class Commands I have made 6 help items in class 'Commands' 1> type s:Help.File | #FILE ram:HelpFiles.ppa | #CLASS Commands | delete | * | 1 | ram:helpfile3.pp | format | * | 80 | ram:helpfile3.pp | list | * | 138 | ram:helpfile1.pp | dir | * | 81 | ram:helpfile1.pp | copy | * | 125 | ram:helpfile2.pp | this | * | 98 | ram:helpfile2.pp Oops ! Something went wrong ! I didn't need a help-item named 'this' ! But this is no problem. Simply edit 's:Help.File' and change 'this' to 'move'. So everything is allright. Let's try it. 1> help del | command delete | ... (help for delete) There are still two things I have to do. First I want to put the archive 'HelpFiles.ppa' on my disk, because it won't live very long on my ram disk. 1> copy ram:HelpFiles.ppa df0: Now I change the FILE option in 's:Help.File'. I add two other lines because I want the help output in the PPMore window. 1> type s:Help.File | #FILE df0:HelpFiles.ppa <<< | #MEMORY PPMore <<< | #RUN <<< | #CLASS Commands | delete | * | 1 | ram:helpfile3.pp | format | * | 80 | ram:helpfile3.pp | list | * | 138 | ram:helpfile1.pp | dir | * | 81 | ram:helpfile1.pp | copy | * | 125 | ram:helpfile2.pp | this | * | 98 | ram:helpfile2.pp Everything is ready ! ============================================================================== End of Quick HELP 1.2 document ==============================================================================