/*****************************************************************************/ /* Copyright (C) 2021 NORMAN MEGILL nm at alum.mit.edu */ /* License terms: GNU General Public License */ /*****************************************************************************/ /*34567890123456 (79-character line to adjust editor window) 2345678901234567*/ /* Part 1 of help file for Metamath */ /* The content here was split into help0() and help1() because the original help() overflowed the lcc compiler (at least before version 3.8; not tested with 3.8 and above). */ /* To add a new help entry, you must add the command syntax to mmcmdl.c as well as adding it here. */ #include #include #include "mmvstr.h" #include "mmdata.h" #include "mmcmds.h" #include "mmhlpa.h" /* help0 is mostly for TOOLS help */ void help0(vstring helpCmd) { /* 5-Sep-2012 nm */ vstring saveHelpCmd = ""; /* help0() may be called with a temporarily allocated argument (left(), cat(), etc.), and the let()s in the eventual print2() calls will deallocate and possibly corrupt helpCmd. So, we grab a non-temporarily allocated copy here. (And after this let(), helpCmd will become invalid for the same reason.) */ let(&saveHelpCmd, helpCmd); g_printHelp = !strcmp(saveHelpCmd, "HELP"); H("This utility assists with some common file manipulations."); H("Most commands will perform an identical operation on each line of a file."); H("Use HELP ? to see list of help topics."); H("Note: When an output file is created, any previous version is renamed,"); H( "with ~1 appended, and any ~1 renamed to ~2, etc. (up to ~9, which is lost)."); H("Note: All string-matching command arguments are case-sensitive."); H(""); H("Line-by-line editing commands:"); H(" ADD - Add a specified string to each line in a file"); H(" CLEAN - Trim spaces and tabs on each line in a file; convert characters"); H(" DELETE - Delete a section of each line in a file"); H(" INSERT - Insert a string at a specified column in each line of a file"); H(" SUBSTITUTE - Make a simple substitution on each line of the file"); H(" TAG - Like ADD, but restricted to a range of lines"); /*H(" LSUBSTITUTE - Substitute according to a match-and-substitute list");*/ H(" SWAP - Swap the two halves of each line in a file"); H("Other file processing commands:"); H(" BREAK - Break up (parse) a file into a list of tokens (one per line)"); H(" BUILD - Build a file with multiple tokens per line from a list"); H(" COUNT - Count the occurrences in a file of a specified string"); /*H(" FORMAT - Produce a formatted list of tokens for documentation");*/ H(" NUMBER - Create a list of numbers"); H(" PARALLEL - Put two files in parallel"); H(" REVERSE - Reverse the order of the lines in a file"); H(" RIGHT - Right-justify lines in a file (useful before sorting numbers)"); H(" SORT - Sort the lines in a file with key starting at specified string"); H(" MATCH - Extract lines containing (or not) a specified string"); /*H(" LEXTRACT - Extract lines containing (or not) strings from a list");*/ H(" UNDUPLICATE - Eliminate duplicate occurrences of lines in a file"); H(" DUPLICATE - Extract first occurrence of any line occurring more than"); H(" once in a file, discarding lines occurring exactly once"); H(" UNIQUE - Extract lines occurring exactly once in a file"); H( " (UNDUPLICATE, DUPLICATE, and UNIQUE also sort the lines as a side effect.)"); H(" UPDATE (deprecated) - Update a C program for revision control"); H(" TYPE (10 lines) - Display 10 lines of a file; similar to Unix \"head\""); /*H(" COPY, RENAME - Similar to Unix cat, mv but with backups created");*/ H( " COPY - Similar to Unix \"cat\" but safe (same input & output name allowed)"); H(" SUBMIT - Run a script containing Tools commands."); H(""); /* 3-Jun-2016 nm Reorganize a little */ H("Command syntax ([] means optional):"); H(" From TOOLS prompt: TOOLS> [ ...]"); /* if (listMode) { H(" From VMS shell: $ DO TOOLS [] [ ...]"); H(" From Unix/DOS shell: tools [] [ ...]"); } */ H("You need to type only as many characters of the command as are needed to"); H("uniquely specify it. Any arguments will answer questions automatically"); H("until the argument list is exhausted; the remaining questions will be"); H("prompted. An argument may be optionally enclosed in quotes. Use \"\" for"); H("default or null argument."); H(""); H("Notes:"); H("(1) The commands are not case sensitive. File names and match strings"); H("are case sensitive."); /* H("(2) Output files are created only after a command finishes running."); H("Therefore it is usually safe to hit ^C before a command is completed."); H("(3) The file \"zztools.tmp\", which is always created, can be used as a"); H("command file to re-run the command sequence with the SUBMIT command."); */ H("(2) Previous versions of output files (except under VMS) are renamed with"); H("~1 (most recent), ~2,...,~9 (oldest) appended to file name. You may want"); H("to purge them periodically."); H("(3) The command B(EEP) will make the terminal beep. It can be useful to"); H("type it ahead to let you know when the current command is finished."); /* H("(6) It is suggested you use a \".tmp\" file extension for intermediate"); H("results to eliminate directory clutter."); */ H(""); /* H("Please see NDM if you have any suggestions for this program."); */ g_printHelp = !strcmp(saveHelpCmd, "HELP ADD"); H("This command adds a character string prefix and/or suffix to each"); H("line in a file."); H("Syntax: ADD "); /* 2-Jul-2011 nm Added TAG command */ g_printHelp = !strcmp(saveHelpCmd, "HELP TAG"); H("TAG is the same as ADD but has 4 additional arguments that let you"); H("specify a range of lines. Syntax:"); H(" TAG "); H("where"); H(" = input/output file"); H(" = string to add to beginning of each line"); H(" = string to add to end of each line"); H(" = a string to match; if empty, match any line"); H(" = the 1st, 2nd, etc. occurrence of to start the range"); H(" = a string to match; if empty, match any line"); H(" = the 1st, 2nd, etc. occurrence of from the"); H(" start of range line (inclusive) after which to end the range"); H("Example: To add \"!\" to the end of lines 51 through 60 inclusive:"); H(" TAG \"a.txt\" \"\" \"!\" \"\" 51 \"\" 10"); H("Example: To add \"@@@\" to the beginning of each line in theorem"); H("\"abc\" through the end of its proof:"); H(" TAG \"set.mm\" \"@@@\" \"\" \"abc $p\" 1 \"$.\" 1"); H("so that later, SUBSTITUTE can be used to affect only those lines. You"); H("can remove the \"@@@\" tags with SUBSTITUTE when done."); g_printHelp = !strcmp(saveHelpCmd, "HELP DELETE"); H("This command deletes the part of a line between (and including) the first"); H("occurrence of and the first occurrence of (when both"); H("exist) for all lines in a file. If either string doesn't exist in a line,"); H("the line will be unchanged. If is blank (''), the deletion"); H("will start from the beginning of the line. If is blank, the"); H("deletion will end at the end of the line."); H("Syntax: DELETE "); g_printHelp = !strcmp(saveHelpCmd, "HELP CLEAN"); H("This command processes spaces and tabs in each line of a file"); H("according to the following subcommands:"); H(" D - Delete all spaces and tabs"); H(" B - Delete spaces and tabs at the beginning of each line"); H(" E - Delete spaces and tabs at the end of each line"); H(" R - Reduce multiple spaces and tabs to one space"); H(" Q - Do not alter characters in quotes (ignored by T and U)"); H(" T - (Tab) Convert spaces to equivalent tabs"); H(" U - (Untab) Convert tabs to equivalent spaces"); H("Some other subcommands are also available:"); H(" P - Trim parity (8th) bit from each character"); H(" G - Discard garbage characters CR,FF,ESC,BS"); H(" C - Convert to upper case"); H(" L - Convert to lower case"); H(" V - Convert VT220 screen print frame graphics to -,|,+ characters"); H("Subcommands may be joined with commas (but no spaces), e.g., \"B,E,R,Q\""); H("Syntax: CLEAN "); g_printHelp = !strcmp(saveHelpCmd, "HELP SUBSTITUTE") || !strcmp(helpCmd, "HELP S"); H("This command performs a simple string substitution in each line of a file."); H("If the string to be replaced is \"\\n\", then every other line will"); H("be joined to the one below it. If the replacement string is \"\\n\", then"); H("each line will be split into two if there is a match."); H("The specifies a string that must also exist on a line"); H("before the substitution takes place; null means match any line."); H("The is an integer (1 = first occurrence on each line, etc.)"); H("or A for all occurrences on each line."); H("Syntax: SUBSTITUTE "); H("Note: The SUBSTITUTE command may be abbreviated by S."); g_printHelp = !strcmp(saveHelpCmd, "HELP SWAP"); H("This command swaps the parts of each line before and after a"); H("specified string."); g_printHelp = !strcmp(saveHelpCmd, "HELP INSERT"); H("This command inserts a string at a specified column in each line"); H("in a file. It is intended to aid further processing of column-"); H("sensitive files. Note: the index of the first column is 1, not 0. If a"); H("line is shorter than , then it is padded with spaces so that"); H(" is still added at ."); H("Syntax: INSERT "); g_printHelp = !strcmp(saveHelpCmd, "HELP BREAK"); H("This command breaks up a file into tokens, one per line, breaking at"); H("whitespace and any special characters you specify as delimiters."); /* 3-Jul-2020 nm Added: */ H("Use an explicit (quoted) space as to avoid the default"); H("special characters and break only on whitespace."); H("Syntax: BREAK "); g_printHelp = !strcmp(saveHelpCmd, "HELP BUILD"); H("This command combines a list of tokens into multiple tokens per line,"); H("as many as will fit per line, separating them with spaces."); H("Syntax: BUILD "); g_printHelp = !strcmp(saveHelpCmd, "HELP MATCH"); H("This command extracts from a file those lines containing (Y) or not"); H("containing (N) a specified string."); H("Syntax: MATCH "); g_printHelp = !strcmp(saveHelpCmd, "HELP SORT"); H("This command sorts a file, comparing lines starting at a key string."); H("If the key string is blank, the line is compared starting at column 1."); H("If a line doesn't contain the key, it is compared starting at column 1."); H("Syntax: SORT "); g_printHelp = !strcmp(saveHelpCmd, "HELP UNDUPLICATE"); H("This command sorts a file then removes any duplicate lines from the output."); H("Syntax: UNDUPLICATE "); g_printHelp = !strcmp(saveHelpCmd, "HELP DUPLICATE"); H("This command finds all duplicate lines in a file and places them, in"); H("sorted order, into the output file."); H("Syntax: DUPLICATE "); g_printHelp = !strcmp(saveHelpCmd, "HELP UNIQUE"); H("This command finds all unique lines in a file and places them, in"); H("sorted order, into the output file."); H("Syntax: UNIQUE "); g_printHelp = !strcmp(saveHelpCmd, "HELP REVERSE"); H("This command reverses the order of the lines in a file."); H("Syntax: REVERSE "); g_printHelp = !strcmp(saveHelpCmd, "HELP RIGHT"); H("This command right-justifies the lines in a file by putting spaces in"); H("front of them so that they end in the same column as the longest line"); H("in the file."); H("Syntax: RIGHT "); g_printHelp = !strcmp(saveHelpCmd, "HELP PARALLEL"); H("This command puts two files side-by-side."); H("The two files should have the same number of lines; if not, a warning is"); H("issued and the longer file paralleled with empty strings at the end."); H("Syntax: PARALLEL "); g_printHelp = !strcmp(saveHelpCmd, "HELP NUMBER"); H("This command creates a list of numbers. Hint: Use the RIGHT command to"); H("right-justify the list after creating it."); H("Syntax: NUMBER "); g_printHelp = !strcmp(saveHelpCmd, "HELP COUNT"); H("This command counts the occurrences of a string in a file and displays"); H("some other statistics about the file. The sum of the lines is obtained"); H("by extracting digits and is only valid if the file consists of genuine"); H("numbers."); H("Syntax: COUNT "); g_printHelp = !strcmp(saveHelpCmd, "HELP TYPE") || !strcmp(helpCmd, "HELP T"); H("This command displays (i.e. types out) the first n lines of a file on the"); H("terminal screen. If n is not specified, it will default to 10. If n is"); H("the string \"ALL\", then the whole file will be typed."); H("Syntax: TYPE "); H("Note: The TYPE command may be abbreviated by T."); g_printHelp = !strcmp(saveHelpCmd, "HELP COPY") || !strcmp(helpCmd, "HELP C"); H("This command copies (concatenates) all input files in a comma-separated"); H("list (no blanks allowed) to an output file. The output file may have"); H("the same name as an input file. Any previous version of the output"); H("file is renamed with a ~1 extension."); H("Example: \"COPY 1.tmp,1.tmp,2.tmp 1.tmp\" followed by \"UNIQUE 1.tmp\""); H("will result in 1.tmp containing those lines of 2.tmp that didn't"); H("previously exist in 1.tmp."); H("Syntax: COPY "); H("Note: The COPY command may be abbreviated by C."); g_printHelp = !strcmp(saveHelpCmd, "HELP UPDATE"); H("This command tags edits made to a program source. The idea is to keep"); H("all past history of a file in the file itself, in the form of comments."); H("UPDATE was written for a proprietary language that allowed nested C-style"); H("comments, and it may not be generally useful without some modification."); H("Essentially a (Unix) diff-like algorithm looks for changes between an"); H("original and a revised file and puts the original lines into the revised"); H("file in the form of comments. Currently it is not well documented and it"); H("may be easiest just to type UPDATE and answer the questions."); H("Try it on an original and edited version of a test file to see if you"); H("find it useful."); H("Syntax: UPDATE "); g_printHelp = !strcmp(saveHelpCmd, "HELP CLI"); H("Each command line is an English-like word followed by arguments separated"); H("by spaces, as in SUBMIT abc.cmd. Commands are not case sensitive, and"); H("only as many letters are needed as are necessary to eliminate ambiguity;"); H("for example, \"a\" would work for the command ADD. Command arguments"); H("which are file names and match strings are case-sensitive (although file"); H("names may not be on some operating systems)."); H(""); H("A command line is entered typing it in then pressing the key."); H(""); H("To find out what commands are available, type ? at the \"TOOLS>\" prompt."); H(""); H("To find out the choices at any point in a command, press and you"); H("will be prompted for them. The default choice (the one selected if you"); H("just press ) is shown in brackets (<>)."); H(""); H("You may also type ? in place of a command word to tell"); H("you what the choices are. The ? method won't work, though, if a"); H("non-keyword argument such as a file name is expected at that point,"); H("because the CLI will think the ? is the argument."); H(""); H("Some commands have one or more optional qualifiers which modify the"); H("behavior of the command. Qualifiers are indicated by a slash (/), such as"); H("in ABC xyz / IJK. Spaces are optional around the /. If you need"); H("to use a slash in a command argument, as in a Unix file name, put single"); H("or double quotes around the command argument."); H(""); H("If the response to a command is more than a screenful, you will be"); H("prompted to \" to continue, Q to quit, or S to scroll to end\"."); H("Q will complete the command internally but suppress further output until"); H("the next \"TOOLS>\" prompt. S will suppress further pausing until the next"); H("\"TOOLS>\" prompt."); H(""); H("A command line enclosed in quotes is executed by your operating system."); H("See HELP SYSTEM."); H(""); H("Some other commands you may want to review with HELP are:"); H(" SUBMIT"); H(""); g_printHelp = !strcmp(saveHelpCmd, "HELP SUBMIT"); H("Syntax: SUBMIT [/ SILENT]"); H(""); H("This command causes further command lines to be taken from the specified"); H("file. Note that any line beginning with an exclamation point (!) is"); H("treated as a comment (i.e. ignored). Also note that the scrolling"); H("of the screen output is continuous."); H(""); H("Optional qualifier:"); H(" / SILENT - This qualifier suppresses the screen output of the SUBMIT"); H(" command."); H(""); H("SUBMIT can be called recursively, i.e., SUBMIT commands are allowed"); H("inside of a command file."); g_printHelp = !strcmp(saveHelpCmd, "HELP SYSTEM"); H("A line enclosed in single or double quotes will be executed by your"); H("computer's operating system, if it has such a feature. For example, on a"); H("Unix system,"); H(" Tools> 'ls | more'"); H("will list disk directory contents. Note that this feature will not work"); H("on the pre-OSX Macintosh, which does not have a command line interface."); H(""); H("For your convenience, the trailing quote is optional, for example:"); H(" Tools> 'ls | more"); H(""); let(&saveHelpCmd, ""); /* Deallocate memory */ return; } /* help0 */ /* Note: help1 should contain Metamath help */ void help1(vstring helpCmd) { /* 5-Sep-2012 nm */ vstring saveHelpCmd = ""; /* help1() may be called with a temporarily allocated argument (left(), cat(), etc.), and the let()s in the eventual print2() calls will deallocate and possibly corrupt helpCmd. So, we grab a non-temporarily allocated copy here. (And after this let(), helpCmd will become invalid for the same reason.) */ let(&saveHelpCmd, helpCmd); g_printHelp = !strcmp(saveHelpCmd, "HELP CLI"); H("The Metamath program was first developed on a VAX/VMS system, and some"); H("aspects of its command line behavior reflect this heritage. Hopefully"); H( "you will find it reasonably user-friendly once you get used to it."); H(""); H("Each command line is a sequence of English-like words separated by"); H("spaces, as in SHOW SETTINGS. Command words are not case sensitive, and"); H("only as many letters are needed as are necessary to eliminate ambiguity;"); H("for example, \"sh se\" would work for the command SHOW SETTINGS. In some"); H("cases arguments such as file names, statement labels, or symbol names are"); H("required; these are case-sensitive (although file names may not be on"); H("some operating systems)."); H(""); H("A command line is entered by typing it in then pressing the key."); H(""); H("To find out what commands are available, type ? at the MM> prompt,"); H("followed by . (This is actually just a trick to force an error"); H("message, since ? is not a legal command.)"); H(""); H("To find out the choices for the next argument for a command, press"); H(" and you will be prompted for it. The default choice (the one"); H("selected if you just press ) is shown in brackets (<>)."); H(""); H("You may also type ? in place of a command word to force Metamath to tell"); H("you what the choices are. The ? method won't work, though, if a"); H("non-keyword argument such as a file name is expected at that point,"); H("because the CLI will think the ? is the argument."); H(""); H("Some commands have one or more optional qualifiers that modify the"); H("behavior of the command. Qualifiers are indicated by a slash (/), such as"); H("in READ set.mm / VERIFY. Spaces are optional around / and =. If you need"); H("to use / or = in a command argument, as in a Unix file name, put single"); H("or double quotes around the command argument. See the last section of"); H("HELP LET for more information on special characters in arguments."); H(""); H("The OPEN LOG command will save everything you see on the screen, and is"); H("useful to help you recover should something go wrong in a proof, or if"); H("you want to document a bug."); H(""); H("If the response to a command is more than a screenful, you will be"); H("prompted to ' to continue, Q to quit, or S to scroll to end'."); H("Q will complete the command internally but suppress further output until"); H("the next \"MM>\" prompt. S will suppress further pausing until the next"); H("\"MM>\" prompt. After the first screen, you can also choose B to go back"); H("a screenful. Note that B may also be entered at the \"MM>\" prompt"); H("immediately after a command to scroll back through the output of that"); H("command. Scrolling can be disabled with SET SCROLL CONTINUOUS."); H(""); H("**Warning** Pressing CTRL-C will abort the Metamath program"); H("unconditionally. This means any unsaved work will be lost."); H(""); H("A command line enclosed in quotes is executed by your operating system."); H("See HELP SYSTEM."); H(""); H("Some additional CLI-related features are explained by:"); H(""); H(" HELP SET ECHO"); H(" HELP SET SCROLL"); H(" HELP SET WIDTH"); /* 18-Nov-05 nm Was SCREEN_WIDTH */ H(" HELP SET HEIGHT"); /* 18-Nov-05 nm New */ H(" HELP SUBMIT"); H(" HELP UNDO (or REDO) - in Proof Assistant only"); /* 21-Oct-2016 */ H(""); g_printHelp = !strcmp(saveHelpCmd, "HELP LANGUAGE"); H("The language is best learned by reading the book and studying a few proofs"); H("with the Metamath program. This is a brief summary for reference."); H(""); H("The database contains a series of tokens separated by whitespace (spaces,"); H("tabs, returns). A token is a keyword, a