# # Help routines and man page from here on # # update $cmds so that we just load once $cmds{"help"} = '&help($arg)'; # a mnemonic to put in the menu, routine to call, and description %help_screens = ( 'A', 'A &help_about About SoftList', 'a', 'a &help_add The Add Menu', 'b', 'b &help_batch The Batch Menu', 'e', 'e &help_editing Editing Lines', 'k', 'k &help_keystrokes Menu Keystrokes', 's', 's &help_search The Search Menu', 'm', 'm &help_main The Main Menu', 'o', 'o &help_options The Options Menu', 'r', 'r &help_references The References Menu', 'c', 'c &help_shell The Perl Shell (CLI)', ); # help - entry point to help routines sub help { local ($which_help) = @_; ($mnemonic, $routine, $menu_item) = split (/ /, $help_screens{$which_help}, 3); print TTYOUT <<"+++"; $clear_str $menu_item ($mnemonic) Press the space bar to get help for \"$menu_item\"... Or, any other key for a menu of available help topics +++ print TTYOUT "\tyour choice >> "; &flush; read (TTYIN, $ans, 1); if ($ans =~ ' ') { print TTYOUT "$menu_item\n"; } else { print TTYOUT "\n\n\tavailable help items:\n\n"; foreach $help_item (sort (values %help_screens)) { ($mnemonic, $ignore, $menu_item) = split (/ /, $help_item, 3); print TTYOUT "\t$mnemonic\t$menu_item\n"; } print TTYOUT "\n\tyour choice >> "; &flush; read (TTYIN, $ans, 1); ($mnemonic, $routine, $menu_item) = split (/ /, $help_screens{$ans}, 3); print TTYOUT "$menu_item\n"; } eval $routine; print TTYOUT "\n"; 1; } sub help_main { if (! defined ($help_main_str)) { $help_main_str = <<"+++"; Main Menu Help and Overview SoftList is used to manage simple lists. You can use existing sets of records, or generate new types of lists on the fly. One example is the "Current Versions of Software" list. SoftList contains a few interactive menus with options for working with the list. It also contains a Perl command line interpreter, and through the use of aliases, can run Unix commands. The Main Menu currently looks like this: SoftList Main Menu $init_message ? help a add b batch in/out s search/edit o options q quit your choice >> The top line of every menu will sometimes show you a message such as "(initialising catalog)". This shows that SoftList is gathering data that it needs. Any menu can be accessed by a single keystroke. To get back from a menu, tap the spacebar. Looking at the menus: a add You'd type 'a' to get to the Add Menu. This menu allows you to enter new list entries, one record at a time. b batch in/out You can feed SoftList an entire file of entries, in order to add records to your data directory. You can also produce a sorted list of all of the records. s search/edit This menu allows you to search for specific records, and to manipulate the ones that are found (edit, view, mail, print). o options This menu will grow in future releases. At the moment, it gives you access to the man page and the Perl CLI. More help about using the menus (they can be pushed and popped) can be found in the "Menu Keystrokes" item. +++ } &pager (*help_main_str); 1; } sub help_add { if (! defined ($help_add_str)) { $help_add_str = <<"+++"; Add Menu Help The Add Menu is used to enter new records, one at a time, to the current list. It shows the current values for the main fileds of the list, and whether the description has been edited. It also displays whether or not this information has been saved. The Add Menu currently looks like this: Add Menu $init_message ? help current values: $saved_stat, $num_data_files data files $dir_menu_msg [replace this with the Softlist version....] p package "$package_name" c contact "$contact_name" l location "$package_location" d description $descstat b batch input r reset variables u update your choice >> Looking at the fields: p package "$package_name" c contact "$contact_name" l location "$package_location" These three fields share a line editor that you use to enter the information (see the help item for "Line/Field Editing"). You can scroll backwards or forwards through history to speed entry. Contacts will usually be the email address or the author of the package, or the maintainer, or the name of a Usenet newsgroup where the package is discussed. The location should the name of an ftp site, and the absolute pathname of the package, or some sort of archiving info. d description $descstat When you enter 'd', you will be put into an editor where you can enter a one or more line description. You can type as much as you want. Remember though, that SoftList separates one record from another by a blank line. b batch input This is a shortcut to the Batch Menu. r reset variables This clears the currently entered patterns. It does not change the status of the description. u update This updates the data directory with your new record. To get back to the Main Menu from the Add Menu, tap the space bar. More help about using the menus (they can be pushed and popped) can be found in the "Menu Keystrokes" item. +++ } &pager (*help_add_str); 1; } sub help_batch { if (! defined ($help_batch_str)) { $help_batch_str = <<"+++"; Batch Menu Help The Batch Menu is used to generate new records from existing files, and to output files that represent some or all of your records. Put another way, someone could email you a file of lots of information on software packages, and if it is in the right format, SoftList can grab the data right out of the file. The "Right Format" looks like this: package: gcc 1.40 contact: gnu.gcc.bug location: prep.ai.mit.edu:/pub/gnu GNU C Compiler package: emacs 18.57 contact: gnu.emacs.* location: prep.ai.mit.edu:/pub/gnu The GNU editor, written by Richard Stallman and a cast of thousands It is important to have a blank line between records. The Batch Menu currently looks like this: Batch Input/Output Menu $init_message ? help i input new records from file o output all records to a file O output only recently found records to a file current in: $current_batch_file_in current out: $current_batch_file_out your choice >> Looking at the fields: i input new records from file Upon pressing 'i', you will get a prompt for which file to use as input. A default path is put there for you. If that path is okay, just hit the return key, and processing will start. In the case of duplicate records, you will be notified. Making batches from standard input is currently not supported. o output all records to a file This works pretty much the same as above. The file prompt is for the name of the file you want everything written out to. O output only recently found records to a file This is like "output all records", except you are just working with the set of records found in the most recent search from the search menu. current in: $current_batch_file_in current out: $current_batch_file_out These two lines show you the current input and output batch files. To get back to the previous menu from the Batch Menu, tap the space bar. More help about using the menus (they can be pushed and popped) can be found in the "Menu Keystrokes" item. +++ } &pager (*help_batch_str); 1; } sub help_search { if (! defined ($help_search_str)) { $help_search_str = <<"+++"; Search Menu Help The Search Menu is used to search for records. It currently looks like: Search/Edit Menu $init_message $num_data_files data files total${last_found_str} $dir_menu_msg ? help [replace this weith SoftList version.....] Search by: Actions: p package A add c contact E edit l location M mail g globally P print R reset patterns V view $reference_option Current Search Pattern: "$search_pattern" your choice >> Looking at the fields: $num_data_files data files total${last_found_str} $dir_menu_msg This line shows the total number of records, and can also show the number found from the last search. Search by: Actions: From this point down in the menu, the things that you can do fall into one of two categories: you can search by package, contact, location, or on entire records, or, on the Actions side, you can do something with the search or perform other tasks. Actions are invoked by capital (shifted) letters, in order to free up lower case letters for the search fields. p package c contact l location g globally These are different ways to search through records. Searches by "package" (p) are the fastest, because each package name is already known by SoftList. The Actions are: A add Go to the Add Menu E edit Go into $ENV{'EDITOR'} to change the found records. M mail Mail the found records to someone. P print Print the found records. R reset patterns Clear the search pattern V view View the records in a pager ($ENV{'PAGER'}) To get back to the Main Menu from the Search Menu, tap the space bar. More help about using the menus (they can be pushed and popped) can be found in the "Menu Keystrokes" item. +++ } &pager (*help_search_str); 1; } sub help_options { if (! defined ($help_options_str)) { $help_options_str = <<"+++"; Options Menu Help The Options Menu is not very developed yet. When SoftList becomes "SoftList" in a future version, there will be more to do here. The Options Menu looks like: Files, Configuration, and Options $init_message ? help e evaluate perl expressions m man page for SoftList If you type 'e', you will drop into the Perl Shell. You can get back from the Perl Shell by just pressing Return by itself on a line. This option is the same as pressing '@' from any menu, except here it happens to be a menu item. 'm' gives you a man page for SoftList. It is very sparse at the moment, because so much help for the program can be found in these help screens. To get back to the Main Menu from the Search Menu, tap the space bar. More help about using the menus (they can be pushed and popped) can be found in the "Menu Keystrokes" item. For more info about Line editing (helpful in the Perl Shell), see the "Editing Lines" item. There is also help available on the Perl Shell. +++ } &pager (*help_options_str); 1; } sub help_shell { if (! defined ($help_shell_str)) { $help_shell_str = <<"+++"; The Perl Shell The Perl Shell is a Command Line Interpreter. It uses all of the line/field editing and history that you find elsewhere in SoftList (see the help item on "Editing Lines"). By editing your ~/.SoftListrc, you can permanently add aliases that enable you to mix Perl statements with Unix commands. You can also cd and push and pop directories. I'll explain a few aliases that I have defined: rc - reconfigure the ~/.SoftListrc file from within SoftList. This is an easy way to add new aliases and other variables to an existing SoftList session. Whatever is in the ~/.SoftListrc is eval'ed by Perl once you exit the editor. A note of caution: only add one thing at a time, and it will be much easier to solve possible problems. alias - with no arguments, show all of the alias definitions. With one argument, show the definition for that alias. You could define a new alias by doing something like: alias sq print "\\n", \$alias_args[1] * \$alias_args[1] catalog - see the existing file that SoftList uses and constructs that maps package names to actual data file names. cd - this is the same as the "cd" command in most shells. You can edit the $cdpath array in ~/.SoftListrc to make getting around easier. crc16 - run perl based crc on a file. This calls a routine in SoftList. You could also make an alias to run an external crc. See the comments in the ~/.SoftListrc file. dirs - examine directory stack l & ll - aliases for the ls command. m - view a file through a pager pkeys - show the package names p, pl, pp & ppl - push, push and list, pop, and pop and list. These all are for the directory stack. prass - print an associative array. This will show you any associative array that SoftList knows about, in a pager. Try: prass %all_packages sha - set shell alias on the fly. This is a shortcut way to define an alias to run a Unix command when you really need to. Let's say you want to run "cc", and get: perl /files/home/users/dansmith>> cc foo.c syntax error in file (eval) at line 1, next 2 tokens "cc;" Since "cc" isn't an alias, and it is not a perl keyword, SoftList doesn't recognize it. You can then do: perl /files/home/users/dansmith>> sha cc perl /files/home/users/dansmith>> cc foo.c and then it will work. upcat - force an update to the current SoftList catalog file. This would useful if you just added a lot of records, and then wanted to view the catalog file. What SoftList usually does is rebuild the catalog file (if needed) upon startup; the theory being that you will use it more to look up existing records than to add to it. To see the bindings of the edit commands, you can try: prass %edit_cmds This will not work well in the "more" pager. Try using "less", as it can handle printing control characters correctly. +++ } &pager (*help_shell_str); 1; } sub help_editing { if (! defined ($help_editing_str)) { $help_editing_str = <<"+++"; Editing Lines/Fields SoftList has a built in line editor to help make entering information easy. Also, for any field, you can retrieve lines you've previously entered. Notation: when I write "C-p", it means the keystroke "Control p". "ESC" means to press the "Escape" key. "BS" is "Backspace", and "DEL" means the "Delete" key. Something like "ESC-b" would mean the sequence "Escape b" (no space is typed). History: Every field maintains its own copy of lines you've entered since you've started SoftList. For example, the Add Menu has a field called "location". For example, let's say you are entering information about a few software packages that are all stored at the site export.mit.edu. For the first record, you would type out "export.mit.edu:/some/long/path". The next time you come to the "location" field, you can enter the keystroke for previous-history, which is C-p (Control p), and edit the filename portion of the path, and save yourself much typing. The keystrokes for history are: C-p previous_history C-n next_history Line Editing: SoftList has many of the same functions and keystrokes as the command line interpreter, tcsh. They are largely derived from Emacs: C-a beginning_of_line C-b backward_char C-f forward_delete_char C-e end_of_line C-f forward_char C-k kill_line (current point to the end) C-l redraw_line C-r redraw_line C-t transpose C-u kill_whole_line C-w kill_backward_word C-x kill_to_beginning ESC escape_prefix BS backward_delete_char DEL backward_delete_char ESC-! run_shell ESC-b backward_word ESC-d kill_forward_word ESC-f forward_word ESC-DEL kill_backward_word ESC-BS kill_backward_word ESC-ESC expand_known_word The line editor is always in "Insert Mode", meaning that you can go backwards on the line and insert characters at any point just by typing. Try typing a few characters, hitting C-a, and then typing a few more. Now, to get to the end of the line, enter C-e. To have SoftList act on your line, hit the Return key. If you are in the middle of typing a line, and need to run a shell command to look something up, enter ESC-! (Escape Exclamation). When you are finished with your shell, SoftList will redraw the line you were working on, and you can continue entering it. +++ } &pager (*help_editing_str); 1; } sub help_keystrokes { if (! defined ($help_keystrokes_str)) { $help_keystrokes_str = <<"+++"; Menu Keystrokes SoftList is intended to be very interactive, by responding to each keystroke in each menu without requiring you to hit Return. Whenever you see a line like: b batch in/out It means that the key in the first column will get you to the menu or function shown next to it. You will see the prompt "your choice >> " whenever SoftList is expecting a single keystroke. Quitting SoftList You quit SoftList by pressing 'q' at the Main Menu. From elsewhere in the program, you need to get to the Main Menu if you want to exit this way. Another possibility is to type "exit" in the Perl Shell. (See the help item "The Perl Shell" for more info) Pushing and Popping Menus Every time you go into a menu, SoftList remembers where you came from. This can be thought of as "pushing" a menu. To "pop" back out, tap the spacebar. A quick example would be: from the Main Menu, type 'a' to go to the Add Menu. Now, tap the spacebar, and you will be back in the Main Menu. There are some additional keystrokes available that are not shown in the menus, that are intended to be helpful shortcuts: Pushing a Main Menu: From any menu, you can get to the Main Menu by entering 'ESC' (the "Escape" key). Pushing a Perl Shell: From any menu, you can push a Perl Shell by entering '@' (the "at sign"). Pushing a Bourne Shell: From any menu, you can push a Bourne Shell by entering '!' (an exclamation). Going back to a Previous Menu: From any menu, enter '-', and you will return to the last menu you were at. For more info about Line editing (helpful in the Perl Shell), see the "Editing Lines" item. There is also help available on the Perl Shell. +++ } &pager (*help_keystrokes_str); 1; } sub help_references { if (! defined ($help_references_str)) { $help_references_str = <<"+++"; the references help is not yet defined +++ } &pager (*help_references_str); 1; } sub help_about { if (! defined ($help_about_str)) { $help_about_str = <<"+++"; $about_str SoftList, a generalized list keeper and Perl CLI This is the successor to SoftList. It will handle the "Current Versions Of Software" list, as well as any other simple list (phone list, CD listing, etc.) you care to make up. I can be contacted via the email address below. If you enjoy using this environment, send me a postcard from your neck of the woods. If this is being used in a commercial enterprise, financial feedback will help to assure patches and continued development :-) Daniel Smith P.O. Box 613 Sausalito, CA 94966 email: dansmith@autodesk.com +++ } &pager(*help_about_str); 1; }