APDL Public Domain 1/APDL_PD1A.iso/textutil/jgpsuite/xmp/EXALIEN

Text File | 1992-09-06 | 11.9 KB | 273 lines

.setu 10 :arc:
.setm 1 *
.nost
!\t\s1 \t}*                     for undentation, see below
.setend : } :
.makel dent                     indented layout
.setend : ]:
.makel meta                     discussion layout
.setend ::
.ht 7 12
.setst :\h2:
.makel list                     listing layout
.setst ::
.setc A.1
.hd
/
.if \o
.col
Page \p|Notes|\s0
.else
.col
\s0|Notes|Page \p
.fi

/
.ft
:

.col
30/11/87|(C) JGLaski, 1988|AL2/8/88

:
One inconvenience I have found with some software packages is that the screen
dialogue etc. has been designed for a foreign culture to my own. I therefore
kept in mind, during development of JGPrint, the desirability of enabling a
JGPrint user to reformulate for her colleagues the various messages JGPrint
provides; this must, of course be tempered by the need to keep things simple
and efficient behind the scenes. Future plans include giving JGEd an analogous
internationalism.

Therefore, while developing JGPrint, I separated the code from the strings
used by JGprint in its dialogue with the user; the characters with which the
user is to respond are taken to be the head of strings used mostly to specify
buttons in the desktop reports. I also separated from the code the actual
strings used in the dotty directives. I have thus built in access to what was
first conceived as a development tool to enable an 'alien' JGPrint with
substantially non\-English dialogue to be constructed if required.

The file containing these is
.if \u10 eq arc
 JGPstrings
.else
 JGPSTRS.CHR
.fi
 and each string is indexed by a name such as strc.55 that helps me with
maintenance, but is not used by JGPrint.

I would advise against attempting this operation without backing this file up
very securely indeed under some suitable name; it is most unlikely that you will
get what you want the first time you try. Moreover, to test thoughrouly you will
have to construct mini\-JGPrint examples to throw up a sufficient subset of
complaints for you to feel safe.

Since what follows requires extensive use of .SET(ST/END) and undented
(hanging indent) lines, I decided to combine the main discussion with a
discussion of startstrings and endstrings; I have even shown a right undent,
an available facility that, frankly, I have not yet found a genuine practical
use for.

.pushl meta
This example text shows how .setend can be used to mark lines, as these are
marked with ']'. Any text that discusses this use is so marked. .setst with a
tab as the startstring can, in association with .nost, be used for left
undentation, and any discussion of this will be marked with a '}' on the
right. A left '[' is now set.
.setst : [:
\ \ \|
aa\w\w\|
.bar .

.col
This is|a dot colled|line
As will be seen from the previous three lines, a .bar line, an empty line and
a .col line are not bracketted by this mechanism; the two lines preceeding
these show two different devices to obtain a blank bracketted line. To save
you going to the source text, they are:
.hln
.col
|\\ \\ \\ \\||;|
.col
| aa\\w\\w\\||.|
.hln
The first works by making a line consisting of a word of two hard spaces; the
second by fooling the readword routine to put out an empty word by giving it
two 'a's and then wiping them out with two '\\w'. The first uses fewer
keystrokes but the second, I think, is more elegant.

In writing the preceeding paragraph, I had a genuine need, for the first time,
to use a '|' within a .COL; this gives me hope that in two or three years
time, I will suddenly find a need for a right undent (see above).

.noend
Here is a demonstration of the use of .noend to produce a right\-undented
line. As I have said, I don't know of a genuine use for it; I shall be glad to
hear from any user who has one.
.popl

.cp 12
The files used to incorporate alienstrings provide 2 groups of information:

\t\s2 \t}strings used in JGPrint;
.hln
\t\s2 \t}Dotty words to be recognised in the text.

These groups are separated by one or more blank lines. The string group must
not contain blank lines. Each line contains one string terminated by a space,
and followed by comments. See below for more detailed discussion.

The Dotty words are separated by either spaces or a newline; comments cannot
be interspersed.

There are certain restrictions on the flexibility provided:
.pushl list

.nost
! \t\s1=1 \h2.The Copyright messages cannot be changed since I have
forbidden it, and "JGPStrings missing" and "not enough space" because they are
encountered before the messages are read in.

.nost
! \t\s1 \h2.Certain strings 'wrap around' others using %s as described below.
Where these enclosing strings are just spaces, newlines and punctuation, they
have not been made available for changes.

\u1Certain strings are needed, if needed, before the JGPStrings has been read
in; these cannot therefore be supplied by JGPStrings.

\u1Certain strings are the result of recent developments. I prefer to keep
these out of the changing mechanism until they have settled down, and
experience has shown that they are best placed and best formulated.

\u1The most important restriction, however, concerns the inclusion of values
within the string, by using the percentage escapers %s(tring), %c(haracter) or
%n(umber). For discussion of their meaning, see below. It is essential that
any string the user provides as an alternative contains precisely the same
sequence of %-escape characters. More precisely, no more than the same number
of these as exists in the corresponding string in the original file should be
included, and, in particular, a use of %s in an incorrect position will
produce garbage on screen, and can cause serious inconvenience.

\u1*n, which stands for newline, should almost certainly be kept in similar
positions in corresponding strings, in order to keep to the layout of the
lines on the screen.

.usel dent
The preceeding list is laid out to demonstrate left\-undenting. The text is
justified between a left margin indented 12 characters and the standard right
margin. The first line is undented, with '!' at the left margin, and with the
section number (letter) in the 7th character position. This is more complicated
than is usually needed, but shows what can be done, and from which a subset
can be chosen according to any particular need.

It is effected by first setting tab stops at character positions 7 and 12 by
the directive .ht 7 12 <nl>. The directive .setst :\\h2: then sets an 11
character startstring to effect the indentation. The use of this directive
forces, if required, a newline at the end of the preceeding text. To cancel
the indentation, set a null startstring by .setst ::. This too may force a
newline.

..nost is weaker than .setst ::. It cancels the startstring just for the
immediately following line (after, possibly, forcing a newline); the
indentation of the letters is simply achieved by putting in the tab \\t.
As used here, this enables numbered points to be pleasantly laid out; some
systems, perhaps observing particular users (eg. the UK Civil Service),
identify section numbering, which to me is a matter of content, with starting
a new paragraph, which to me is a matter of form. JGPrint's system provides
the flexibility to keep the two facilities separate; those who disagree with
me can easily practice their rigid rules.

The directives needed to arrange undenting and numbering and aligning the
first word of the line with the indented text are somewhat fiddly, so, after
the first use, which was slightly special in that it needed to reset section
numbering, and the second which I left to show explicitly the full details, I
used \\u1, a user string that I had defined for this purpose. Here it is:-
.hln
..setm 1 /
..nost/
!\\t\\s1 \\t}/
.hln
I normally put such a definition in the prologue, and therefore use a .SETM; a
..SETU would have interpreted the tabs at the point of definition. Since they
were not yet defined, there would, I trust, have been a diagnostic! More
seriously, the tabs are required not to be put into effect until they are
reached when interpreting the line.

Notice also the use of .popl to return to the base layout, even though we have
left the layout originally pushed onto the stack. Had the directive for dent
been .pushl dent, we would have had to use two .POPLs to get back to the
original layout.

.popl
.col
|The syntax of the strings

Strings can force the incorporation of additional parameters by the use of the
percentage escapers. Thus, for example, the prompt "Configured for 's'
OK('c')? :", is supplied by JGPrint with a string parameter, e.g. "Screen"
found from within the configuration file, and a character parameter, e.g. 'Y'
found as the head of a certain other string.

The string supplied must contain markers, \U}viz\V %s and %c, where, in the
description above, 's' and 'c' were used, to force these supplied parameters
to be included. Any occurrence of % in a string will assume that this
is a marker for some kind of inclusion, and that the next character will
specify what kind. At present, and, indeed, for the forseeable future, these
are just S/s for strings, C/c for characters and N/n for (decimal) numbers. If
the next character is not one of these the '%' is ignored, and the next
character printed. In practice, this means that to get a '%' printed, two '%'s
must be put into the string. The similarity of these rules to those governing
the provision of codestrings for printers in the configuration file should be
noted.

One string per line is taken in, and, roughly speaking, the string found on
the nth. line will be the one supplied as JGPrint calls for the nth. string.
Therefore, precisely the same number of lines as are found in JGPstrings must
be provided in any alternative <stringfile> supplied. An empty line is
unacceptable. Use a single character if you want to save space.

Any space characters at the beginning of a line are gobbled, and characters
are then read into a string until a space or newline is encountered; any
characters following this space are ignored, and can be used, as 'str?.??' are
in JGPStrings, for comments. (These I use to help me maintain JGPrint, but
if I were producing a <stringfile> to replace JGPStrings, which I did not
need for maintenance, I might use the strings of the original JGPStrings as
comments.) These rules present a problem as to how to put spaces and newlines
into the strings, and '*' is used as an escape character with *s signifying
space and *n newline. Thus the example above is actually supplied as:-
.hln
.col
|Configured*sfor*s%s*nOK?(%c)?*s:
.hln
Notice that no quotation marks should be supplied; if they occur, they will be
incorporated verbatim. (BCPL afficionados should note that no other *<escape>
codes are provided.) In the event that strings are included in a diagnostic
report (see below), *s and *n will have been translated into space and
newline.

.col
|The size of strings and Diagnostics

JGPrint begins by reading in JGPStrings, and putting the strings and the dotties
in space provided for them, setting up, on the way, various internal
data\-structures.

JGPrint knows how many strings, and dotties to expect, and if the file
JGPStrings has a mismatch, it will report, say, using strd.96,
.col
|*n%n*sstrings*ssupplied.*s%n*srequired
that some strings are missing, or, whatever I have judged to be a suitably
informative message, and abandon the run.

If JGPStrings is edited to begin with a '.', various diagnostics are provided to
confirm that the strings are being correctly read in.

For historical reasons, JGPrint provides space within the code for the strings
read in. For this reason, the strings could have too many characters to fit,
and, if so, a "too many characters" report is provided, which includes an
indication of whereabouts in the strings this overflow occurs. This will appear
whether or not the '.' for diagnostics was set.