-*-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:: What to do when you move your 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  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). The /& switch allows you to suppress the table of contents. 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. 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 listed source can be printed in multiple fonts to increase legibility. If you specify more than one font, the actual 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. 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 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. @ provides this service. @ is compatible with all text justifiers because it operates on the output of the text justifier, the file to be printed on the XGP. 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. 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. 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. 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): /# 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 file name and page number, should also contain the current date. This flag now defaults on. /& Suppress the title page at the front of the listing, and also the lists of printed and deleted pages and the page map. * /@ 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 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. /F[,,] Tells @ that the specified 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 references). A font spec is really a file spec; the defaults are appropriate for the system you are using (on its, DSK:FONTS;... KST). Fonts specified will be remembered in an LREC file. Variable-width fonts can be used, but don't expect @ to figure out cleverly 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 "L" should be followed by the name of the language, enclosed in square-brackets. There should be no spaces between the "L" and the open-bracket. 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), "RANDOM" (which means that the file is intended only for human consumption), and "TEXT" (which means that the file is a document output by a text justifier). However, "MIDAS" is the default and need not be mentioned. Thus, "(L[FAIL] X)" specifies fail code being listed for the XGP. * /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.) Useful for restarting listings lost in a crash. 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 linel 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). If is 0 (the default case), 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 default VSP is 4 (or whatever comes from an LREC file). The default page height is more complicated. If fonts and VSP have not been specified, either in the command or from an LREC file, the default is 60. If fonts or VSP have been specified, the default is the right number of lines of that font to fit on a normal 11 inch XGP page with normal margins. /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 XGP line, with normal margins. /X XGP output (also implied by F switch). /X[QUEUE] Do queue the output files for the XGP. /DELETE is used, so that the file will be deleted a few minutes after it is printed. /X[NO] Do not queue the output files for the XGP. You must queue them by hand later. /X[GOULD] Queue the output files for the Gould printer in Building 38 (on MC). Use -X[GOULD] to get LPT style listings (these come out faster). /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, "@XGP" for XGP output, and "@CREF" for auxiliary output files (see /C and /U). On TOPS-10, the defaults are "LST", "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 What to do when you change the names of some of your source files. 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.