6 : Creating the text

The Header and \ Commands

The text area file for !Draw which you create using !Edit is not quite like any other text file. Special formatting commands can be inserted; these are all introduced with the backslash character "\". In addition, the text file must begin with a special header sequence. If this is omitted, !Draw may ignore the file altogether, generate an error message or substitute a default header. The header must begin with the line:

    \! 1

The space is optional. The number, called the version number, must be 1 otherwise an error message will be generated when the file is transferred to !Draw.

The header typically contains details of the fonts to be used, their sizes, line spacing, margins, alignment, the number of columns or boxes and the text and background colours. Most of these effects have default values. This means that, if you do not define them, the software will itself choose a value.

If a text file lacking a version number line is imported into !Draw, the following "default header" is attached to the text:

    \! 1
    \F 0 Trinity .Medium 12
    \F 1 Corpus-Medium 12
    \0
    \AD
    \L12

This defines Font 0 as 12 pt Trinity Medium, Font 1 as 12 pt Corpus Medium, selects Font 0 as the current font and sets the line spacing to 12 pt with "double justification", ie both left- and right-hand edges to be straight.

The full list of "\" commands is as follows. Note that all commands are case sensitive so you cannot use lower-case letters in place of capitals as this will cause errors. Most commands must be terminated by a <CR> or a slash (/), but some, particularly font-change commands, need no termination unless it is necessary to avoid ambiguity.

\! Version line

This line must begin your text file or the default header will be substituted. The \! must be followed by the version number which must be 1. The command must be terminated by a / or a <CR>. For example:

    \!1

\A Alignment

The \A must be followed immediately by one of the following: L (left); R (right); C (centred) or D (double). The command may be terminated by a /, but this is optional. For example:

    \AD

This causes following text to be printed with double alignment.

• Left alignment means that the left margin is straight, but the right margin is ragged, as in conventional typing.
• Right alignment means that the right margin is straight, but the left margin is ragged. This effect is useful for certain display purposes and also in letter headings.
• Centred alignment means that the text is centred between the margins. This is useful in titles, sub-titles, letter headings and other forms of display.
• Double alignment means that the text has both left and right margins straight as in most books, newspapers and magazines. The spaces between words are evenly expanded to bring lines to the full width.

\B Set background colour

The B must be followed by three numbers between 0 and 255, separated by spaces. The numbers represent the proportions of red, green and blue respectively in the new background colour. Values greater than 255 are treated as 255 and values less than 0 are treated as 0. The command must be terminated by a <CR> or a /. For example:

    \B0 0 0/

This sets the background colour to black. The default is:

    \B255 255 255/

This sets the background colour to white.

Note that changes to the background colour are not effective unless the specified colour is already present in the area. Also a "bug" in the printer driver software may cause problems in printing text areas that are not in the default colours.

\C Set text colour

The C must be followed by three numbers between 0 and 255, separated by spaces. The numbers represent the proportions of red, green and blue respectively in the new text colour. Values greater than 255 are treated as 255 and values less than 0 are treated as 0. The command must be terminated by a <CR> or a /. For example:

    \C255 255 255/

This sets the text colour to white. The default is:

    \CO O O/

This sets the text colour to black.

\D Set number of columns or boxes

D must be followed by a number in the range 1 to 99 and the command must be terminated by a <CR> or a /. The default number is 1. The command must appear before any text is printed. For example:

    \D 6

This would cause the text to appear in six columns or boxes which subsequently can be re-sized and rearranged to suit the layout of the document.

\F Define font

The F must be followed by a font number (any number in the range 0 to 99), then by the filename for the font to be allocated that number, then by the font size in points. Optionally the font width may be defined after the font size; if omitted it is set to the same value as the font size. Spaces are compulsory between all items in the command except between the \F and the font number. The command must be terminated by a / or a <CR>. For example:

    \FO Trinity.Medium 12
    \F1 Trinity.Medium.Italic 12
    \F2 Trinity.Bold.Italic 12
    \F10 Trinity.Medium 9
    \F99 Trinity.Bold 12 16

This sequence of commands defines five fonts from the Trinity family. Normally these definitions will be in the header. In this document the appearance of text will depend on the preceding symbol as follows:

  Symbol       Following text
    \0      12 pt Trinity Medium
    \1      12 pt Trinity Medium Italic
    \2      12 pt Trinity Bold Italic
    \10      9 pt Trinity Medium
    \99     Extended 12 pt Trinity Bold

Extended text has an extra bold appearance.

As can be seen, font numbers need not be assigned sequentially. If the same font is to be used in two different sizes (like Trinity Medium in the example), a separate definition is needed for each size.

When the text file is transferred into !Draw, the program will attempt to ensure that the specified fonts are present in the ! Fonts directory. If any of the specified fonts are not present, an error message ("Unable to Load Font <filename>") is given, and another font, usually the one previously used, is substituted.

\L Set line spacing

The \L must be followed by a number; a space is optional between the \L and the number. The command must be terminated by a <CR> or a /.

The number is the line spacing in points. This is the distance from the base of the characters in the current line to the base of the characters in the next line. For example:

    \L 12/

This sets (or changes) the line spacing to 12 pt 1/6 inch). The command often appears in the header, but it need not do so. If omitted, a default line spacing of 10 pt is applied. You may also use the command at any point in the text where you wish to change the line spacing. The change of spacing takes effect from the end of the line (in the !Draw text area) in which the command falls.

\M Set margins

The \M must be followed by two numbers separated by a space. A space is optional between the \M and the first number. The command must be terminated by a <CR> or a /.

The command sets or changes the margins, ie the space between the edges of the column or box (as revealed using the 'select' facility in !Draw) and the text itself. The first number is the left margin in points and the second number is the right margin in points. The new margin settings apply immediately if executed at the beginning of a line. Otherwise they apply from the end of the line in which the command appears. By default both margins are 1 pt. For example:

    \M36 1/

This sets the new left margin to 36 pt (1/2 inch) and the right margin to 1 pt. The command is useful for applying temporary indents in text areas.

Note that it is possible to make the margins so large that they meet or overlap, squeezing out the text altogether. This does not cause an error, but it does prevent the text from appearing.

\P Set paragraph spacing

The \P must be followed by a number; a space is optional between the \P and the number. The command must be terminated by a <CR> or a /.

The number is the spacing in points that will be inserted between paragraphs. For example:

    \P 24/

This sets the space between paragraphs to 24 pt (1/3 in). To create a new paragraph in a text file press <CR> twice. On the !Edit screen this starts two new lines, so that a blank line appears between paragraphs. In the text area in !Draw the blank line will be replaced by a space having the value set. If the value is the same as the current line spacing, a blank line of standard spacing will appear between paragraphs. If the value is 0 no extra space will be inserted between the paragraphs; the new paragraph will start immediately below the previous one. A value equal to half the current line spacing gives an effect that many find pleasing-it separates paragraphs by half a line space.

The command often appears in headers, but need not do so. If omitted, a default value of 10 pt is assumed. The command may be inserted at any point in the text file where you wish to change the amount of space between paragraphs. The new value takes effect at the end of the paragraph in which it is placed. This can be very useful if you wish to space out the paragraphs so that they exactly fill adjacent columns. Note that you may also create new paragraphs having no intervening space by terminating the paragraph with \<CR>. This simply forces a new line. The effect is exactly the same as <CR><CR> after a \PO/ command. A single <CR> (not preceded by \) is treated by !Draw as a space (for reasons that are explained later).

\U Underline

The \U is followed by the underline position (a number in the range - 128 to 127) and the underline thickness (a number in the range 0 to 255). A space is compulsory between the two numbers and optional between the \U and the underline position. The command must be terminated by a / or a <CR>. Both numbers are in units of ^1/256th of the current font size. For example:

    \U -128 26/

This turns on underlining of 1 pt thickness (a 10 pt font is assumed) at the lowest possible position, which on most fonts is well below the tips of the descenders. In general a position setting of about -70 looks good. Aim for a thickness of about 1 pt.

If the position number is set to 127, this sets the underline position to about half a font height above the base line, at about the same level as the tops of lower case characters such as c and n. So unfortunately, this facility cannot be used to insert bars above words and symbols as used in describing logic functions.

To turn underlining off, either set a new underline having thickness 0, or, more conveniently, issue the following:

    \U.

The shorthand command \U. may be terminated with a / but this is not strictly necessary.

\V Vertical move

\V must be followed by a single-digit number in the range -9 to 9. A space is optional between the \V and the number. The command must be terminated by a / or a <CR>. The number is the number of points by which the following text must be moved upwards. Negative numbers, of course, move the text downwards.

The purpose of this command is to allow the inclusion of subscript and superscript characters. These will normally need to be in a font approximately half the size of the one in general use. For example:

    H\V-4/\1/2\V4/\0O

will print H20 assuming that the current font is a 12 pt font assigned to font 0 and font 1 is same font in 6 pt size.

If you wish to use superscript or subscript figures 1, 2 and 3, note that there is a simple way to do so. The Acorn outline fonts include superscript figures 1, 2 and 3 in ASCII codes 185, 178 and 179 respectively. These can be selected in the normal way. To convert them to subscript simply use a \V command to lower the printing position by a suitable amount (roughly half the font size).

After issuing a \V command, remember to issue another \V command having the same value but of opposite sign to restore printing to its normal level.

\<CR> Start new line

This forces the start of a new line. An isolated <CR> is regarded as equivalent to a space. To start a paragraph you are recommended to press <CR> twice. This starts a new line and inserts before it the space set by the \P command.

\- Soft hyphen

!Draw normally only splits lines at spaces. You may, however, insert \- into a long word, which indicates to !Draw that it may split the word at this position, inserting a hyphen, if it needs to. If it does not need to, the command has no effect.

\ [font number] Change font

The font number must be a number between 0 and 99 and must follow the \ without any intervening space. The font number must have been assigned to a font using a \F command earlier in the text. The command may be terminated bv a / but this is not strictly necessary. However, it is advisable to insert the . it the text character immediately following it is a number.

This command may be issued at any point in the text where a change of font is required, such as a change from roman to italic characters or a change to a smaller font for superscript or subscript printing.

\\ Insert \ character

Since the \ character is used to identify embedded commands, this special provision has been made for those occasions when you may wish to actually print a backslash in your document.

\; Comment

This allows you to write comments in your text file. The comments will appear on screen in '.Edit, but will not appear on screen in !Draw text areas or in printouts. All text following \; up to the next <CR> is regarded as comment.

This facility, which is equivalent to REM in BASIC program listings, is most useful for reminding yourself of the purpose of some piece of text.

Paragraphs and <CR> Characters

Unless you deliberately set your text editor to format the text there will normally be no <CR> characters in the text except where you have pressed the RETURN key. Since the lines of text on the screen in !Edit are likely to be broken in different places from those in the text area in !Draw, it is clear that <CR> cannot have its normal new line effect in !Draw.

The rules concerning the way !Draw treats <CR> characters in text areas are as follows:

• An isolated <CR> is treated as a space.
  
• A <CR> preceded by a space or followed by a space is ignored.
  
• A <CR> preceded by a \ forces a new line.
  
• Two <CR>s in sequence start a new paragraph separated by the space specified in the last issued \P command; if no \P has been issued the default space of 10 pt is applied.
  
• A sequence of n <CR> characters inserts n-1 paragraph spacings.
  
• Paragraph spacings at the start of the text are ignored.