Enter your search terms Submit search form
	Web pdp-10.trailing-edge.com

-*-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<cr>.  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 definition-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 <tag>,
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.
	/<N>A	Arbitrarily long symbol names should be retained by @,
		but when the symbol table is printed symbol names
		should be truncated to <N> 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[<FILE>]
		Is the same as "CU[<file>]" - 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[<device>]
		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[<dev>] can be combined as /-D[<dev>].
	/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.  <N>F simply sets
		the number of fonts to be used, while
		F[<font1>,<font2>,<font3>] sets the names of
		fonts as well.  *Note Fonts: Output.
	/F[<font1>,<font2>,<font3>]
		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.
	/<N>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[<language>]
		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[<l>,<t>,<r>,<b>,<h>]
		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.  <l>, <t>, <r> and
		<b> refer to the left, top, right and bottom of the
		page when oriented so that the printing is right side
		up.  <h>, 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[<file>]
		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.
 *	/<N>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 <CRLF> 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.
	/<n>S	Allocate space for <n> 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.)
	/<n>U	Universal symbol tables.  If <n> 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 <n> is 0 (the
		default if /U is not used), each file's symbol table
		will be normal (list only that file's symbols).
		If <n> is positive, the files' symbol tables
		will be normal, but there will be <n> 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[<file>]
		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
		<last data file> @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.
	/<n>U[<file>]
		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.
	/<n>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 that 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-
			<char+100 ASCII>
		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/_<CR>.
		The ASCII description goes in a file  DLREC >
		(DLREC.LST on TOPS-10) on the default directory
		(it can be moved with a /O[<defaults>] - 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[<defaults>] 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[<file>] or /U[<file>] 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.