-*-Text-*-  File: @ Node: Top, Up: (DIR), Next: Basic The @ program makes cross-reference listings of programs. One or many files can be listed together. On each line will appear the file, page, and line of the definition of a symbol referenced on that line. Comparison listings can be made, containing only the pages changed since the previous listing, for both programs and text-justifier output files. * Menu: * Basic:: Simplest usage of @, for programs. * Output:: What @ output looks like, for programs. * Text:: Simplest usage of @, for papers. * Assembler:: What @ understands about assembler language. * Lisp:: What @ understands about Lisp. * Muddle:: What @ understands about Muddle. * Quotes:: Quotes (') control whether files are listed. * Switches:: What you can do with command line switches. * Files:: What files are used, and their default names. * Substitutions:: Adding, removing or changing names of source files.  File: @ Node: Basic, Up: Top, Previous: Top, Next: Output Fundamentals of @ for programs: When you make a listing, you must initially specify the names of the files to be listed, the language they are written in, and various other parameters. All of this information, is remembered in a special "LREC" file just for that purpose. To make an update listing, you need only specify the name of the LREC file; all other information is read from there. Comparison listings work by keeping in the LREC file a table of checksums of all the pages of each source file. When it is time to make the update listing, the new source file's pages' checksums are compared with those listed in the LREC file. A page whose checksum has changed needs to be listed. This scheme means that it is not necessary to retain the copy of the program which was last listed. The LREC file is all that is necessary for making an update listing. When you list a program THE FIRST TIME, your command should resemble :@ RMS;FOO LREC/G/L[LISP]/F[20FG],RMS;FOO,BAR,BLETCH "RMS;FOO LREC/G" says that the LREC file should be called RMS;FOO LREC. "/G" always indicates the name of the LREC file. @ will see that the LREC file does not already exist and type "(LREC file new - listing all files in full)". The rest of the command says that the program is contained in RMS;FOO >, BAR >, and BLETCH >, is written in LISP, and should be printed in the font 20FG. The output from @ will be three files FOO @XGP, BAR @XGP, and BLETCH @XGP. All three will be printed on the XGP and deleted. The /L and /F are "global" switches (*Note Switches: Switches.) which apply to the whole listing. They can appear anywhere in the command string, and it doesn't matter where they go. The /L[LISP] switch says that the program is written in LISP. The /F[20FG] switch says that the output should be printed in the font 20FG; it also implies, by default, that the output files should be printed on the XGP and then deleted. To make UPDATE LISTINGS of all the files composing a program, you need only specify the LREC file. The names of the source files and the switches to be used, as well as the comparison data, are taken from the old LREC file. That file is renamed to OLREC, and a new LREC file containing updated comparison data is written. :@ RMS;FOO/G You need not specify the name LREC this time, because @ can figure it out since the file already exists. While all switches will default to the values read from the LREC file, you can override any of them by explicitly specifying it. For example, if you want to switch to font 18FG from now on, you can just include "/F[18FG]" in the command string. This listing, and future listings until you specify /F again, will use 18FG. From time to time, repeated insertions and deletions of pages will cause page numbers such as "3/24" to exist (suppose you inserted 24 pages before page 4). When that happens, you may want to make A NEW FULL LISTING and cause the pages to be renumbered as integers. To go this, just specify "/-G" instead of "/G" when you give the name of the LREC file: :@ RMS;FOO/-G @ can also direct its listings to the Dover. Specify /D[Dover] in the command line to request this. The output file will have a second filename of PRESS, and you must transfer it to the Dover yourself with :DOVER filename. You can specify font names in Dover listings, but the font names are not filenames. A font name consists of the family name, the points size, and the face code. The face code is made up of letters from the set "CELBI", which stand for compressed, extended, light, bold and italic, respectively. The face code is empty for a standard font (neither bold or light, neither extended nor compressed, not italic). Example: the default is LPT8.  File: @ Node: Output, Previous: Basic, Up: Top, Next: Text What @ Output for Programs Looks Like. @ listings of programs can contain all these things: One or two title pages Page maps Subtitle table of contents Listed source Symbol table Cref table. Exactly which are present in a given listing depends on the switches used (*Note Switches: Switches.). The TITLE PAGE is meant to identify the listing. It's most prominent feature is the name of the listed source file, "bigprinted" with letters each built out of a matrix of characters, as in FFFFF OOO OOO F O O O O FFF O O O O F O O O O F OOO OOO The title page also contains the full name and creation date of the file, and the names of all other files included in the listing, as well as the name of the user who made it, and the name of the LREC file (very useful when you want to update the listing). Use the /& switch if you don't want title pages. PAGE MAPS occur only in update listings. They list the numbers of all pages which were printed, and separately list the numbers of all pages which were created or deleted. Note that if you create a new page between pages 4 and 5, neither of which were changed, the new page will be numbered 4/1 in an update listing. The "4" is called the major page number and the "1" is the minor page number. In this case, "4/1" would be listed among the printed pages and among the created pages. The page map will also include a table which matches physical page numbers against the page numbers actually used. Using the same example, you might see 4 4 5 4/1 6 5 The page map is useful for interpreting compiler error messages and SRCCOMs that contain the physical page number in the source file. /& suppresses the page maps as well as the title pages. The SUBTITLE TABLE OF CONTENTS is a list of all the subtitles that appear in the file, in order, with page numbers. It should be self-explanatory. Just what constitutes a page number depends on the language. The /Z switch requests a table of contents. The LISTED SOURCE contains not just the source, but a header line at the top, an optional copyright notice at the bottom, and a line number and cross reference on each line. The header line contains the file name, subtitle, and page number. If a page is too long for the output medium, it is split into "subpages", each short enough to fit, and each with its own header; but lines numbers are within the entire page. Thus, page 4 may be split into subpages 4.0 and 4.1, 4.0 getting lines 1 through 84, and 4.1 getting lines 84 through 122. In addition, if there are inserted pages with nonzero minor page numbers, such as 4/1 and 4/2, they get numbers starting where 4/0 left off, just so that any line can be unambiguously referred to with just the major page number and the line number. This allows cross references to lines to be printed more concisely. The cross reference on each line is @'s trade-mark and most useful feature. It gives the page number and line number (and file name, in a multi-file listing) of one of the symbols referred to on that line. @ heuristically attempts to choose the most "interesting" symbol to cross-reference. For PDP11 code you can get two cross-references on each line. See the /N switch. The line numbers as well can be suppressed with the /# switch. An alternative to having inserted page numbers such as 4/1 is to have all pages listed with their real numbers. This is requested with the /Y switch. For example, if a new page is inserted between 4 and 5, it will be printed as page 5. If page 5 has not changed it will not be printed, but if it has changed it will be printed as page 6. If page 10 has changed, it will be printed as page 11, and so on. The assumption is that the user will cross out the old page numbers on the pages which are not printed, and replace them by their new page numbers, in sequence. An even more extreme alternative is to use /1J or /1G, which says that any page whose physical page number has changed should be relisted even if it has not changed. These modes are not likely to be desirable in languages for which @ can make cross-references, because old cross references in pages which do not change will become incorrect in the page number much more quickly this way. The listed source can be printed in multiple fonts to increase legibility. If you specify more than one font, the listed text uses the second font, and comments use the third font if there are three. The header and the cross reference use the first font, which is also used by all the tables in the listing. Use the /F switch to request this. It is wise to use fixed width fonts except for the comment font (font three). If you would like to prevent @ from ever trying to put text on the first line of a physical page, just put a (possibly null) subtitle in the file. If a file has a TVEDIT directory, @ will never try to put text on the first line of the page, assuming that it won't fit anyway. The switch /1" also insists on not using the first line for any text. On the other hand, /-" can be used to suppress the headers entirely. The SYMBOL TABLE is a relatively dense alphabetical table of all symbols and where (and how) they were defined. Both single-file symbol tables and "universal" (all files sorted together) symbol tables can be requested. If you make a cref, you might not want the symbol table as well; see the /$ switch. In Lisp code, you may find that a few long symbol or efinition-type names cause the symbol table to be printed using a very few wide columns. The /nA switch specifies that all names be truncated to only n characters, in printing the symbol table. This will cause more columns to be used and thus fewer pages to be needed. The CREF table is a list of all definitions and all references for all symbols. The symbols appear alphabetically, at most one on a line; for each symbol, all the definitions and then all the references are listed. The type of definition or reference is also enoded by a special character, which can be looked up in a table appearing at the front of the cref. See the /C switch. In multi-file listings, you can optionally request a UNIVERSAL SYMBOL TABLE, which is a symbol table for all the files put together. Each symbol definition will list the file containing the definition as well as its page and line number. See the /U switch. You can also get a universal table of contents; see the /Z switch. The CREF and UNIVERSAL tables are, in a multi-file listing, not associated with any particular file. Such non-file-specific output is normally appended to the output file for one of the listed files. However, you can specify that an "auxiliary output file" be used instead for non-file-specific output. The auxiliary output file will not be used if all output from a given listing is file-specific. See the /C and /U switches.  File: @ Node: Text, Previous: Output, Up: Top, Next: Assembler Use of @ on Text-justifier Output for Papers. Cross-referencing papers is not usually very meaningful, but it does help to be able to print only pages which have changed. @ in /L[text] mode provides this service. When you wish to print a new update listing, you must first process your paper with the text justifier you are using, and then use @ to extract the pages of the output which have changed. @ operates on the output of your text justifier, and therefore avoids any dependence on the input format for any particular justifier. However, it does assume that the file is already in the correct format for the printing device to be used. Thus, if the device is to be the XGP, the file specified must already be an XGP file; and device Dover is not allowed, because parsing of PRESS files as input has not yet been implemented. Only if the device is LPT will the input file be assumed to be an ordinary ASCII file, but even so, it is assumed to be already paginated. Do not use /L[Text] for printing a file of plain English text, or anything other than the output from a text justifier. English text and languages not parsed by @ require /L[Random]. To make an initial full listing of a paper, and create the LREC file, you use a command like :@ RMS;PAPER LREC/G,PAPER,PAPERX,PAPERY /L[TEXT]/X PAPER LREC/G says that the LREC file should be called RMS;PAPER LREC. The rest says that the XGP files PAPER XGP, PAPERX XGP, and PAPERY XGP should be listed (*Note Defaults: Files, for how filenames are defaulted). Each of those files will make a separate output file, with an FN2 of "@XGP", and those output files will be queued for printing and deleted afterward (*Note Switches: Switches, for other alternatives). To make an update listing, run the text justifier to produce a new version of PAPER XGP, and then do :@ PAPER/G This will re-list the file remembered by PAPER LREC, using the comparison information to tell which pages have changed. Not all of the original input files need exist; only those which have changed. An input file which does not exist will make @ behave as if the file had existed but was identical to the one listed last time (ie, no pages need to be printed). As a result of this, you need not run unchanged files through your text justifier before running @. An EMACS macro has been written (*Note RUNOFF: (INFO;RUNOFF >)*.) which takes advantage of these features of @ to help manage the text processing of large documents with multiple files. When @ is listing a paper it does several special things, which are all necessary: The default FN2 for input files is XGP, rather than >, so that your text justifier's output will be used, rather than the text justifier's input. Pages listed are not given line numbers or header lines; they are copied verbatim. This is because your text justifier presumably provides its own headers. The first page of the file is always included in the output file. This is because it usually contains special commands to the XGP spooler, such as font specifications. Without them, the file will print totally wrong. No title-pages, page maps, etc. are printed before the first page of the paper itself. This is, again, because the special XGP spooler commands must remain at the front of the file. The first non-blank line of each page is ignored for comparison purposes; if a page has changed only in that line, it is not reprinted. This is so that you can, include the date of the current draft, or the file version that generated it, in the header of each page, without thereby causing @ to think that every page has changed whenever you make a new draft.  File: @ Node: Assembler, Previous: Text, Up: Top, Next: Lisp Tips on Programming Style in Assembler Language. A few simple precautions can make @'s left-margin cross references more informative. @ Assumes that a semicolon starts a comment, but only when it follows a space or tab (or at the beginning of a line). So make sure that your comments will be recognized. On the other hand, sometimes you mention a tag in a comment and would like the tag to be cross-referenced. For that, use .SEE , which does nothing at all in MIDAS except provide @ with a reference to mention. @ Will parse MIDAS .INSRT's and FAIL .INSERT's, and add the files so found to the list of files to scan for symbol definitions. The /I switch controls whether or not such files should also themselves be listed. .AUXIL and .LIBFIL: Assembler language files containing the pseudo .AUXIL are regarded as files of auxiliary symbol definitions. Symbols which appear only in input-only auxiliary files will not be mentioned in the cref table. Thus, if your program .INSRT's a file of definitions which contains a .AUXIL, only those of its symbols which your program actually uses will show up in the cref table. .LIBFIL is even stronger; it prevents a file from being processed at all, if it is not being listed. It essentially causes @ to ignore .INSRT's of that file. If your assembler does not define .AUXIL or .LIBFIL, you can put it inside an IFN 0 conditional to avoid an error. An alternative to using .AUXIL in the file is to specify the /: switch for the file; this makes the file auxiliary only in that listing rather than in all listings in which it is referred to. A subtitle in PDP-10 code is started by SUBTTL. A subtitle in PDP-11 code is started by .SBTTL or .STITL. Since @ does not actually assemble the program, symbol definitions and references will be found even if they would be ignored by conditional assembly. This is usually a bonus. On the subject of conditional assembly, always use a comma to separate the condition of a MIDAS conditional from the conditionalized code. @ assumes that you will, and it makes things more readable anyway. @ doesn't expand macros, so symbol definitions in macros will not be understood unless you take precautions to make them visible. One thing you can do is supply the "=" or ":" to be used in defining the symbol as part of the argument to the macro; then the macro call will appear to contain a definition of the symbol. The macro itself can strip off the ":" with an IRPS or IRPNC if necessary. Symbols being defined in an IRPS can be delimited with any character, so use ":". Another principle is that macros should not supply a prefix for the symbol to be defined; if you want a common prefix, put it with the symbol name in the macro call (of course, if the symbol is only referred to from macros that add on the same prefix, you can still win; @ will see the definitions and the uses without the prefix and correctly match them up). If you are generating lots of symbols, you may be quite happy that they are not seen by @. Keyword macro arguments in MIDAS will, of course, appear to be symbol definitions, and show up in the CREF. Simply chosing keywords that are not the same as symbols in the program will prevent that from causing any trouble. @ considers symbols defined on page 1 of a file, or the current page, to be less interesting than other symbols. Also, symbols defined with "=" or equivalents are less interesting than those defined in other ways. Given a choice of symbols for a left-margin cross-reference, @ will use the most interesting one. So, for example, you should put your accumulator definitions on page 1. Often, people use a short name like "A" as a dummy in a macro or IRP, sometimes representing a symbol which is to be defined. When this happens, @ sees a definition of the symbol "A". If "A" is also an accumulator, this will cause a more confusing listing, so make sure that you do not use accumulator names as dummies. All in all, you can't expect @ perform perfectly in its search for symbols, but luckily you are not screwed very badly when it fails.  File: @ Node: Lisp, Previous: Assembler, Up: Top, Next: Muddle A subtitle in Lisp code looks like (COMMENT ...), where if CRLFs appear within the list, only the first line is used. However, if you put "(COMMENT" on a line by itself, no subtitle is recognized. Thus, using COMMENT to comment out some code causes no problems. An alternate way of putting a subtitle into Lisp code is to start a comment with exactly four semicolons in a row. What follows them will be the subtitle. Five semicolons in a row do NOT start a subtitle. The INCLUDE function is recognized, and the included files are searched for symbol definitions (and listed, if the /I switch is set). Although @ initially recognizes the usual functions for defining functions or global variables, you may have your own definers which you would like recognized. You can request that with the @DEFINE function. @DEFINE is a no-op in Lisp itself; it is used only to tell @ that a certain function is a symbol-definer, and uses of it should make entries in the symbol table. You write (@DEFINE FOO BAR) to tell @ that (FOO UGHBLETCH ...) is a definition of UGHBLETCH. An entry will be made in the symbol table saying that UGHBLETCH was defined. Furthermore, the type of definition listed will be BAR. If you use a function whose name starts with "DEF", it will be @DEFINE'd automatically. Thus, (DEFFOO UGHBLETCH) will make an entry in the symbol table saying that UGHBLETCH was defined with DEFFOO, without any special action on your part.  File: @ Node: Muddle, Previous: Lisp, Up: Top, Next: Quotes Currently, subtitles are not recognized in MUDDLE code. When they are implemented, they will be specified by any string beginning with the characters SUBTITLE, e.g., "SUBTITLE main routines...". FLOAD and USE are not recognized; however, parameters and local atoms are recognized and creffed.  File: @ Node: Quotes, Previous: Muddle, Up: Top, Next: Switches The Singlequote Character in Command Lines. Somewhat like a switch is the single-quote ('). With a data (non-LREC) file, one single-quote indicates that the file should not be listed, just scanned for symbol definitions (to which cross-references may appear in files that are listed). Two single-quotes prevents the file from being processed at all. This is what to do when a program .INSRT's a file which you do not want scanned (or which does not exist). Files specified without a single-quote are listed. With an LREC file, a single-quote can be used to prevent an updated LREC file from being written out. This is very good for making an "experimental" listing, which you suspect you will throw away. Not updating the LREC file means that the same pages will be listed in the next listing.  File: @ Node: Switches, Previous: Quotes, Up: Top, Next: Files Switches go inside the file specs. Some switches are global in effect, and it does not matter which filespec they go in. Other switches are "per-file". Some of them are sticky, and affect the file in whose spec they go and all following files, until countermanded. Global switches are taken from an LREC file, if any, unless you override them by respecifying the switch. Per-file switch settings for each file are taken from the LREC file also, unless the file is also specified explicitly in the command string, in which case ALL per-file switches must be specified in the command string (or allowed to be sticky from an explicit specification with another file earlier in the command string). Switches exist to control: How the source files are parsed. How much of each source file will be listed. The files used for output. The device used to print the output. The geometry of pages in the output. Copyrighting. How inserted pages are to be numbered. The use of overprinting in the output. Which tables are generated, and exactly how they look. Switch Syntax: To identify switches to @, you may either enclose several switches in parentheses, or prefix each switch with a "/". Switches are single characters, possibly preceded by decimal numbers. Use "-" for negative numbers; -X = -1X. For two-state switches, if X turns it on -X will turn it off. Some switches also take trailing arguments enclosed in []; the meaning of such an argument is described below for each individual switch which can take such an argument. Thus, valid switch specifications include (S C-U) or /S/C/-U or (SC)/-U or (L[LISP]54W) or /L[LISP](54W120V)/F[20FG] Spaces or commas between switches in parentheses are ignored. Note that if the /G switch is used, the default values of all switches are those remembered in the input lrec file, except for switches which claim that they are "not remembered in the LREC file". Otherwise, the default setting of a switch is "off", unless otherwise stated. Table of Switches: (* indicates a per-file switch; all others are global switches; default is off (-X) unless otherwise stated): /! Controls handling of input files found not to exist. It says to forget all about the file if the user doesn't supply a new name (that is, if he types just CR) when the error message asks for one. /-! means don't bother complaining; don't list the file but do remember it. /-! is useful for files generated by another program, which will not always all be there. /0! This is the default: @ complains, and if the user doesn't supply a new name, no listing is made but the file is remembered in the LREC file, anyway. /n" Reserve n lines at the top of each page for header information only (no text lines). The first of these would contain just the filename, date and page number, and the subtitle if any. If more than one line is reserved, the remaining lines are blank. /-" Eliminate the header at the top of each listing page, which would normally contain the filename, date, page number and perhaps subtitle. /# Inhibits the printing of anything at all in the left margin, even the line numbers. * /$ Inhibits printing the symbol table for the file. This switch is sticky throughout the command string, defaulting off for the first file. For .INSRT'ED files that were not mentioned by the command string or an LREC file, the /$ switch default is the way the switch was set at the end of reading the command string. /% The headings at the top of each page, which normally contain the current date, do not do so if /-% is spec'd. /& Suppress the title page at the front of the listing, and also the lists of printed and deleted pages and the page map. * /: Makes a file an auxiliary file, which means that symbols defined in it will not appear in the CREF table unless they are used in another file. This is the same as the effect of having .AUXIL in the file. /= The filenames remembered in the LREC file should be the ones specified by the user rather than the real names of the listed file. That is, remember FOO > rather than FOO 24. This was absolutely necessary for someone. I have no idea why. /> Sort all the input files by filename alphabetically, list them in that order, and give their names on the title page in that order. /-> Give the filenames on the title page in alphabetical order but list the files in the order of specification. /0> This is the default: deal with input files always in order of specification. * /@ This file is an LREC file, but use only its comparison data (for detecting unchanged pages); don't use its filenames and switch defaults. /A Arbitrarily long symbols should be kept by @; this is the default for LISP code. /A Arbitrarily long symbol names should be retained by @, but when the symbol table is printed symbol names should be truncated to characters, so as to fit more columns and use up fewer pages. /-A @ should remember only the first 6 characters of symbol names. This is the default for MIDAS code. /C Keep track of all references and print a CREF at the end of the last file output. "/-C" says there should be no CREF. /C[] Is the same as "CU[]" - It specifies the auxiliary output file and requests a CREF. /-C in a later listing would supress the CREF. If this means that there is no no-file-specific output, no auxiliary output file will be written, but @ will not forget that you want non-file-specific output to go in one. To make such output go in the usual place, use /U[NONE:]. /D[] This specifies the printing device which the listing is ultimately destined for: the LPT, the XGP, the Dover, etc. It is not the same thing as the device on which the output file should be written (usually DSK). If the device is Dover and fonts are specified with /F, the /F switch should come after the /D switch. /-D Do not queue the file for printing on the output device. The user will have to arrange for printing. /-D and /D[] can be combined as /-D[]. /E When a reference is made to another file in the left margin, use only the first two characters of the first file name instead of the whole file name. This reduces the width gobbled up by the cross-reference data at some cost of readability. /F Is a dual purpose switch. F simply sets the number of fonts to be used, while F[,,] sets the names of fonts as well. *Note Fonts: Output. /F[,,] Tells @ that the sepcified fonts are to be used. If one of the font names is null, it is considered not specified. There need not actually be three fonts named; only as many as it is desired to specify. Thus, "F[,20FR]" specifies only font 2 (used for the text). Font 1 is used for references, headings, title pages and pages of tables. Font 2 is used for listed text, except that if font 3 is specified it is used for listing comments. (The actual font numbers in output files are 0, 1 and 2). A font spec for the XGP or the Gould is really a file spec; the defaults depend on the system you areusing (on ITS, DSK:FONTS;... KST). A font name for the Dover consists of the family name, the points size, and the face code. The face code is made up of letters from the set "CELBI", which stand for compressed, extended, light, bold and italic, respectively. The face code is empty for a standard font (neither bold or light, neither extended nor compressed, not italic). Example: the default is LPT8. The legal family names are in the font catalog. Since the format is not the same as for the XGP, /D[dover] must preceed the /F switch. Fonts specified will be remembered in an LREC file. It is best to use fixed width fonts, except perhaps for the comment font (font three). If that font is a variable width one, don't expect @ to be clever about where to break lines. /F Use the specified number of fonts on output. Implies the X switch (XGP). If two fonts, then reference data uses the first font and text the second font. For three fonts, comments use the third font, where a comment is text on a line following a semicolon preceded by tabs or spaces. * /G Identifies the LREC file name, and specifies that the file names and switch settings specified in the old LREC file should be the defaults for the new listing. The single-quote status of each source file (none, one, or two) will also be remembered. /-G Because the ability to use the remebered switch settings and files is valuable by itself, /-G has the meaning, "use the remembered switch settings and file names, but make a full listing rather than a comparison listing". /1G Specifies an LREC file for filenames and switches like a regular /G, but also causes enough extra pages to be listed when necessary to avoid giving newly created pages names like "5/1", or leaving gaps in the page numbering due to deleted pages. /H On => output ^H as real backspace, causing overprinting. Off => output as uparrow-H (For XGP, if "^" switch is given, output as a quoted Control-H) /I All .INSRT'd files (unless individually inhibited) should be listed. Default is to use them only for the symbol definitions they contain. For LISP code, the INCLUDE function specifies inserted files for this purpose. * /J Controls the amount of reprinting of unaltered pages. /-J causes a new full listing to be made of the file(s) it is specified for. It is the per-file equivalent of /-G. /1J causes reprinting to be done when pages are inserted or deleted, to whatever extent is necessary to avoid creating page numbers like 5/1, or leaving any gaps. /1J is the per-file equivalent of /1G. Neither form of /J is remembered in the LREC file, and both are sticky. To countermand them, use /J. /K Causes SOS line numbers to be listed as if part of the text of the file. Normally, They are ignored. /L[] Is used to specify the source language of the files being listed, telling @ how to find symbol definitions, etc. The language name may be abbreviated. Languages currently known to @ include MIDAS, MACRO-10, PALX11, FAIL, LISP, MUDDLE, UCONS (Lisp-machine microcode), DAPX16 (Honeywell 316 assembler), and RANDOM, which means that the file is not in any format known to @. It could be English text, or a language @ can't parse. The default is MIDAS. There is also a language TEXT, which means that the input file is the output from a text justifier. It is assumed to be in the appropriate format for the printing device which you specify with /D; thus, if you specify /D[XGP], the input must be an XGP file. For a file of English text, use RANDOM, not TEXT. Parsing of PRESS files is not yet implemented, so /L[TEXT]/D[DOVER] is not allowed. /M[,,,,] Specify the page margin sizes, in mils (for graphics printers only). You should not use this switch with the XGP unless you specify fonts as well. The default for each margin is half an inch. , , and refer to the left, top, right and bottom of the page when oriented so that the printing is right side up. , the "hole margin", is added on what is the left side of the paper in its normal orientation (the side where you are expected to punch holes). * /M Identifies the file it is spec'd with as the "MAIN" file. This means that the LREC file version number is synchronized to this file's version number. In more detail, if an LREC file is written, its default fn2 is the real fn2 of the "MAIN" file. For this to be reasonable, the LREC file should either be kept on a different directory from the "MAIN" input file, or should have a different fn1. If neither of those is the case, the default fn2 of the LREC file will be LREC -- otherwise, the LREC file written would overwrite the input file! If you are using the /M feature, you might also want to use /G with the LREC file - that will make the default input fn2 ">", which is just right. /N Omit the cross-reference data on the left margin (but still produce a symbol table and CREF if appropriate). /O Means files are old. This is used for creating LREC files for your old files without listing them, so that you can make comparison listings of the new ones (this is in case you didn't make an LREC file the last time you listed them). The results are the same as if you simply deleted all the listing output files, but /O is more efficient. /O can also be used to build a new LREC up from the current source versions and an old LREC file. /O is not remembered in the written LREC file. /O[] Specifies default output file names. If a single output file is being generated (/S is in use), the complete name may be specified in the /O (but need not be; anything not specified will be defaulted). If /S is not in use, and each data file has its own listing file, ONLY the device and directory name may be specified in a /O, since the filename for each listing file must be left free to default. The /O filenam affects only listing output files. The LREC output file must be specified in front of a "_" in the LREC file spec; the auxiliary output file is controlled by /C or /U. * /P The page number of the first page to be listed. (Default 1.) This switch is not remembered in LREC files. /Q A Qopyright message is printed at the bottom of each page. The default message is: "(c) Copyright 1977 Massachusetts Institute of Technology. All rights Reserved." except that the correct year is substituted. A different message may be specified by using []: /Q[This is a message]. [] may be used in the message if they are balanced, or if quoted by ^Q. /R OFF => only counts as a line-separator. Stray CR's and LF's will appear in the listing as uparrow-M and uparrow-J, except that in XGP listings if the "^" switch is set they will come out as quoted control-M's and control-J's. On => all LF's count as line-separators; Stray CR's cause overprinting. /S Only one single output file should be created, the concatenation of all the output data. /S Allocate space for symbols. Should never be needed on ITS. /T -T (the default) if a line is too long, insert CRLF's. 1T (or just T) => truncate long text lines to fit the linel. 0T => let them run over. (Tables produced by @ always stay within the line length, by design.) /U Universal symbol tables. If is negative, each file's symbol table will be a universal one (will list all symbols in all files). /U with no argument is equivalent to /-U. If is 0 (the default if /U is not used), each file's symbol table will be normal (list only that file's symbols). If is positive, the files' symbol tables will be normal, but there will be extra universal symbol tables printed. They will go in the auxiliary output file if there is one; otherwise, at the end of one of the listing files. /U[] Specifies the name of the auxiliary output file, and that there should be one. The auxiliary output file is used to hold all output not associated with any particular input file. This now means crefs and universal symbol tables. Names not specified in the filespec inside the /U default as they would for other listing output files (based on the /O specification, if any, or to @CREF on your working directory). If LREC files and /G are in use, note that the unspecified names will be re-defaulted each time a listing is made; if the device and sname are unspecified then in each listing the auxiliary output file will go on the same directory as the other output files. /U[NONE:] Specifies that there be no auxiliary output file. What would normally go in it, goes at the end of one of the regular output files. /U[] Combines the two functions of the "U" switch. /V Is a multi-purpose switch, which can set either the page height or the VSP (vertical interline spacing). Given any reasonable page height (>45 or so) the page height is set. Given a reasonable VSP (<= 15) the VSP is set. Given a negative argument, the VSP is set to its absolute value. The VSP is measured in units of XGP dots. For the Dover, one XGP dot corresponds to 13 micas. The default is 4. The default page height is depends on the printing device specified. If the device specified with /D is a graphics printer, then the page height will be calculated automatically based on the fonts and margins you specify. /W Set page width. The default for non-XGP listings is 120. For XGP listings the default is 89 if fonts have not been specified. If fonts have been specified, the default is the number of characters of the widest font, that will fit in an 8.5 inch line, with specified margins. /X The /X switch has two meanings: use graphics features of the output device, and default the device to XGP if not otherwise specified. For some graphics printers, such as the XGP and Dover, @ will insist on using such features, and /X is irrelevant. For others, such as the Gould, you are given a choice, because it is more efficient to print a simple LPT-style listing than one which uses any of the graphics features. /Y Causes @ to assume that the user will re-number old pages. Normally, @ assumes that old pages not replaced keep their numbers, and creates interpolated page numbers like "1/1" when pages are inserted. With /Y, it prints each page with its real number, and expects you to correct the page numbers of pages being carried over from the old listing (a guide telling you how to renumber them is printed). /Z A table of contents should be printed, using subtitles from the various subtitle pseudo-op's. /^ On => control chars are output as themselves (On XGP, they are XGP-quoted if necessary) Off => control chars output as uparrow- When the language FAIL is selected, this switch defaults on; otherwise, off. /_ Print an ASCII description of the contents of the input LREC file. You should use this as follows: :@ FOO LREC/_. The ASCII description goes in a file DLREC > (DLREC.LST on TOPS-10) on the default directory (it can be moved with a /O[] - doing so is not a screw, in the sense that the DLREC file contains the /O information from the LREC file, not the /O you specify.) Switch Example: This is how ITS would be listed now, if the LREC file were lost: :@ SYSENG;ITS(F[20FG] I $ 1U[ITS]),SYSLRC;ITS(G -$) SYSENG;ITS > and all .INSRT'ed files are listed for the XGP with font 20FG. ITS has no symbol table, but every other file has one (because the -$ in the LREC file spec sets the default for .INSRT'ed files). Also, a universal symbol table is put in a file named ITS @CREF on the same directory as the listing files. The reason we don't give the file ITS a symbol table of its own is that it would be a repetition of most of the universal symbol table.  File: @ Node: Files, Previous: Switches, Up: Top, Next: Substitutions Filenames Used by @. Normally, a separate output file is written for each data file, onto the user's working directory (on ITS, for non-XGP listings, onto TPL:). Its first file name is the same as the data file's. Any output not associated with a single file (universal symbol tables, or CREF tables) goes at the end of one of those output files (namely, the last one written). You do have some control, however. The output files can be forced onto a different device or directory with the /O[] switch. You can cause all the listings to go in a single file, rather than one for each data file, with the /S switch, and then you can use the /O switch to specify its name completely. In addition, you can make the non-file-associated output go in a separate file, called the auxiliary output file, and specify its name, with the /C[] or /U[] switches (Filename components not specified in the /C or /U default, as in other output files, to the /O or the working directory/TPL). Any names specified in the /O, /C or /U switches are remembered for future listings; names not specified are defaulted anew each time, and not necessarily always the same way. Thus, if you do not specify a directory name, the output files will, each listing, go on the current working directory of the user making the listing. As for filename defaulting, all the first file names default together stickily. Each second file name defaults for each file separately, according to the file's use. Device names and directory names default stickily data files, starting out as "DSK:" and the user's working directory; however, the LREC file is unaffected by the stickiness. It defaults to DSK: and the user's working directory. The default second name for LREC files is "LREC" ("LRC" on TOPS-10) and "OLREC" ("OLR" on TOPS-10). For data files, the default on ITS is ">"; on TOPS-10, it is the appropriate extension for the language the file is in (as specified by the /L switch). The TOPS-10 version will also recognize the language that a file is written in from its extension, if you specify the extension but not /L. For output files, the default on ITS is "@" for non-XGP output, "PRESS" for Dover output, "@XGP" for XGP output, and "@CREF" for auxiliary output files (see /C and /U). On Bots-10, the defaults are "LST", "PRESS", "XGP" and "ATC", respectively. An alternative naming scheme for LREC files is available on ITS, which matches the LREC file versions with the source versions they describe, by giving the LREC file the same version number as the source. This scheme is useful only with one-file listings, or when there is one file in the listing which is paramount, and which changes far more often than the others. To request it, specify the /M switch with the input file whose version numbers are to be followed by the LREC file. You should then specify the directory and first name of the LREC file as usual, but not the second name (and don't make the directory and first name of the LREC file the same as those of the source file, as you otherwise would be likely to do! Luckily, @ will refuse to clobber the source with the LREC). /M will be remembered in the LREC file so the alternative naming scheme will continue to be used. If you want to change to the normal one, specify /-M in a listing. If you want to change the file whose version numbers are followed, specify /M with the new file to use.  File: @ Node: Substitutions, Previous: Files, Up: Top, Next: Adding Adding, Removing or Changing Names of Source Files * Menu: * Adding:: Adding a source file * Removing:: Removing a source file * Moving:: Moving a source file  File: @ Node: Adding, Previous: Substitutions, Up: Top, Next: Removing Adding a Source File To add a source file to an LREC file, just mention the new source file in the command line just as you would when making a first listing. The new file will be listed in full, while the files already in the LREC file are comparison listed (unless you said otherwise). The new LREC file will remember the additional file along with all the others. For example, given an existing LREC file FOO LREC and a new source file BAR, all you need do is :@ FOO/G,BAR You may specify per-file switches with the new file. Otherwise, they default from the default values remembered in the LREC file.  File: @ Node: Removing, Previous: Adding, Up: Top, Next: Moving Removing a Source File If you remove one of the source files from a program, or for any reason wish it not to be included in any future listings of the program, simply mention in it the command line with two singlequotes. For example, to comparison-list the FOO program but exclude the file BAR from this and all future listings, do :@ FOO/G,BAR'' A doublequote will not do. Use TWO singlequotes. To cause a source file to be processed only as input (symbols defined in it can still be cross-referenced in other files) but not listed, specify the file with one singlequote. If you change your mind and want the file listed again, you can add it just as if it had never been included (*Note Add: Adding.). However, the old comparison data will still be around and the first listing printed will be an update from the last one made before the file was removed. If you want a full listing of the file instead, use /-G or /-J.  File: @ Node: Moving, Previous: Adding, Up: Top Moving a Source File Sometimes, you will change the name of one of the files of a program, or move it to a different directory. When this happens, you must make sure, when you next list the program, that @ obtains that part of the program from the right place. On ITS, the easiest way to do this is to make a link from the old name to the new name. Thus, if SYSENG;FOO > has been moved to SYSTEM;, make a link SYSENG;FOO > to SYSTEM;FOO >. The next listing will obtain the correct file through the link, and in the new LREC file the new names SYSTEM;FOO > will be rememebered. Subsequent listings will use SYSTEM; even if the link is deleted. If it is not convenient to use a link, a translation (see the ^T and $^T DDT commands) will do just as well. If you are moving a file to a new directory, but not changing the first filename, then you can simply specify the file explicitly, with its new names, in the next listing. Because of the matching first names, @ will assume that the specified file is the same one as mentioned in the LREC file, on a new directory. However, it is necessary to respecify all the per-file switches that you want. If all else fails, you can specify the new name of the file explicitly, and specify the old names with two single-quotes to make @ ignore it. On a DEC system, this is probably the only alternative. Unfortunately, it will always make a new full listing of the file that was moved. Of course, you can always delete that listing file.