Typically you will require a title page.  This is a single page, not included in the page numbering, and treated as page 0 for double sided printing purposes - hence it is an even page.

The definition of the title page should be included near the top of the source document, before any regular text.  It would typically be preceded by other word-processing instructions to, say, set the page formatting.

The definition commences with the string "^[titlepage".  There should be no other text on this line; any text found here will be ignored.

All text entered for the title page will be rendered where it is placed.  In other words, the literal mode is automatically engaged.

Typically you would include a title for the document, a version number, a revision date, the site identification, your company details, and so forth on this page.  Some of this information may be referenced symbolically, by calling up macros defined in the header file, especially for the site identification, and possibly also for the version number and revision date.  Please refer to the section titled: "Text Substitution".

You might also want to make use of the text presentation instructions.  Please refer to the section titled: "Text Presentation Options".

The end of the title page is identified by the string "^[end_titlepage".  Again there should be nothing else on this line.

Typically you will require a title for the top of each page.  This can consist of as many lines as you desire, though it is best kept to one or two so as to save paper.

The definition of the page title should be included near the top of the source document, before any regular text, typically just after the title page definition.

The definition commences with the string "^[pagetitle".  There should be no other text on this line; any text found here will be ignored.

All text entered for the page title will be rendered where it is placed.  In other words, the literal mode is automatically engaged.

Typically you would include a title for the document, a version number, a revision date, and a page number.  Some of this information may be referenced symbolically, by calling up macros defined in the header file.  Please refer to the section titled: "Text Substitution".

In particular, you would generally include the page number, optionally introducing it with text such as "Page", then some space, then the string "^[page_number".  The position of the escape character defines the position of the least significant digit of the page number, so you should allow sufficient space between the preceding text, say, "Page" and the escape character to accommodate the more significant digits of the page number.

If the "page_number" instruction appears elsewhere, it will be ignored, and an error message will be entered into the error file.

The end of the page title is identified by the string "^[end_pagetitle".  Again there should be nothing else on this line.

You may partition your document into named sections and subsections.  The major sections of the document are given level 0, with the major subsections of these sections being given level 1, and so on to the maximum depth at level 9.

You are to specify the start of a partition, or section, of your document, using the string "^[level" followed by a space, then the string representing the level from "0" for the major sections of the document to "9" for the most minor sections.  Following this string should be a space.  Any text after the space and before the end of the line is used as the name of the section.

If you relate this to an HTML document, level "0" corresponds to heading "h1", while level "5" corresponds to heading "h6".  The HTML specification only allows for six levels, so levels "6" to "9" are catered for using a "paragraph class" (an HTML term) named "minor_heading" to highlight these headings.

It is best to maintain a uniqueness in the section names, so that hyper-text jumps work as expected, in both the Movement Controller help system and the HTML rendering program.  A section name should be unique among all sections at the same level within the enclosing section.

The level number can be one greater than the level number of the previous "level" instruction, or less than or equal to that number.  It is an error for the level number to be greater than the previous level number by more than one.

You may elect to have a page break at the start of each major section, or at the starts all sections with level numbers equal to or less than a given value by using the string "^[page_break_for_level", followed by a space, then the string representing the level for which a page break will be generated for and for all levels up to this.

For the Movement Controller help system to be context sensitive, it needs to know the which sections or subsections describe which windows.  The windows are specified using the "C" language definitions used by the Movement Controller itself.  The name of the file containing these definitions is, by default, "function.inc", but may be specified on the command line to the word-processor, as an optional field to the "-i" switch.

The contents of the file will be ignored until the text "GetPassword" is found. From this point on it will gather the window names and record the corresponding numbers for each.  These numbers will be written to the help index file, along with a reference to the position within the source document, where the reference to this window was found.

These window references are generated by using the string "^[screen_number", followed by a space, then the string containing the "C" language definition, from within the ".inc" file, for this window.  There should be no other text on this line; any text found here will be ignored.

The first line used from the ".inc" file is "#define GetPassword 1".

For the help system to be able to access the relevant page for the "GetPassword" window, the string "GetPassword" should appear in the source document as the parameter to the "screen_number" instruction.  It should be positioned just after the line containing the "level" instruction for the section describing the use of this window.

As a result, the word processor will include a reference, in the index file, to this point in the source document against window "1", which is how the window would be known within the run-time Movement Controller software.

The index file also contains the full path of the source document, and indexes for the sections and subsections of this document.  In this way a site specific index file is used by the Movement Controller software to access a single source document, without having to setup links to the source document.  It is important, though, that the source document remains where it was when the word processor had been run, because that is the location in which the software will expect to find it.

As an example, the start of the section describing logging onto the computer may appear as follows:

  ^[level 1 Log Off

  ^[screen_number GetPassword
  This window is presented when the Log Off (or New User)
  option is selected from the main menu.

Throughout a document, you will typically wish to refer the reader to another part of the document.  When you do this you should refer to this section by its entire address, which includes all enclosing section and subsection names, separated by dots, and the entire string enclosed in double quotation marks. For example, this section would be referred to as the section titled: "Cross-references and Hyper-Text".

If the string must be broken into lines, the breaks may be made between the words of a single section name, or before the dots separating section names. If line breaks are made between words, ensure that there are no spaces beyond the last word before the line break and the end-of-line (carriage-return line-feed).

The rendering of this reference will depend on whether the manual is printed, presented via the Movement Controller's help system, or presented by an HTML rendering program.

In the printed document (whether using Rich Text Format or printer specific controls), cross-section references are presented using the section and subsection numbers, separated by dots, followed by the final subsection name, and the entire string enclosed in double quotation marks. When presented via the Movement Controller's help system, cross-section references are displayed using the final subsection name, enclosed in double quotation marks and highlighted as a hyper-text link.  When presented via an HTML rendering program, cross-section references are displayed using the final subsection name rendered as a hyper-text link.

Now, in order, to create a hyper-text link to the referenced section, the first double quotation mark of the reference must be preceded by the reference instruction, which is the string "^[reference", followed by a space.

As an example, a reference used earlier in this document might appear as follows:

  Typically you would include a title for the document, a
  version number, a revision date, and a page number.  Some
  of this information may be referenced symbolically, by
  calling up macros defined in the header file.  Please
  refer to the section titled: ^[reference "Ancillary
  Programs.The Word Processor.Writing the Input Files
  .Word-Processing Instructions.Text Substitution".

To refer to a section from another manual, the reference should be written the same way, except that you must include, between the reference instruction and the first quotation mark, some instruction to the reader, indicating that the section is in another book.  The word processor, upon finding this intervening text, will not attempt to interpret the reference, but will, instead, present the reference as it was written.

Should you wish to reference one of the standard manuals, that is the operator's manual, the technical manual, or the software manual, you should include the text, "OPERATOR'S MANUAL", "TECHNICAL MANUAL", and "SOFTWARE MANUAL", respectively.  These will be interpreted by the word processor as instructions to include "operator.htm", "technica.htm", and "software.htm", respectively, within the hypertext references to allow for hyperlinks to exist between these documents.  Similarly, the Movement Controller's online help software will recognise these and use them to, similarly, reference the corresponding header file and main source file.  For example, "OPERATOR'S MANUAL" will direct the online help to the header file, "operator.wph", and the main source file, "operator.wpi"; there is a table hard-coded within the online help software that relates these three items for each of the manuals.

You can use "points" or "bullets" to list items in your document.  We will use the term "point" rather than "bullet" in this discussion.

Each item to be presented as a point, must be preceded by the string "^[point", followed by a space, followed by the point name. The point name may be a string not containing a space, or a string commencing with an escape character followed by a double quotation mark, and terminating with the same pair of characters.

The text, of the item to be presented in the point, may either follow a space following the point name, or else may appear indented on the next line.

The point name need not be unique, and will typically be simply the string "o". This string is a special case for the HTML document, as it will be ignored; all HTML points will be displayed as unnumbered lists, followed by the point name (unless the point name is "o"), then followed by the text.

In the printed documents, and in the Movement Controller help system, each point will be introduced, with the point name presented in bold, followed by the text.  Had the text followed the point name, on the same line, then the text will be presented after the point name, and if it does not fit on a single line, the subsequent lines of the text will line up beneath the first line of text, still to the right of the point name.

Had the point's text started, indented on the line after the point name, then the indentation will be used to indent all lines of the point's text starting on the line below the point name.  If tabs appear in the indentation, they advance the indentation to the next multiple of eight spaces.

For example had you entered:

  ^[point ^["LT in/out of position^["
     This status is always present and indicates whether the
   crane is positioned on a long travel screen.

Then something similar to the following is likely to be printed:

  LT in/out of position
     This status is always present and indicates
     whether the crane is positioned on a long
     travel screen.

Whereas, had you entered:

  ^[point ^["LT in/out of position^[" This status is always
  present and indicates whether the crane is positioned on
  a long travel screen.

Then something similar to the following is likely to be printed:

  LT in/out of position This status is always
                        present and indicates
                        whether the crane is
                        positioned on a long
                        travel screen.

The point's text is either terminated with the next "point" instruction or else at the end of the paragraph.  If however you wish points to include more than a single paragraph within the point's text, you should include the string "^[point_paragraph" before the first point in the list, (or at least first point with multiple paragraphs).  On the first line after the last paragraph of the last point in the list, you should include the string "^[end_point_paragraph", this delimits the last point, whilst the "point" instruction delimited the intervening points.

If you wish a list not to be split across a page break, you should include the string "^[no_page_break_in_points" prior to the paragraph introducing the list, as the list is seen then as an extension of the paragraph.

If on another occasion, you wish to enable page breaks within a list, include the string "^[page_break_in_points" prior to the first point in the list.  When this instruction is in force, page breaks will still not break paragraphs.

It is my habit to include the "no_page_break_in_points" instruction at the beginning of the document, then bracket each list which I wish to be exempted from this with the "page_break_in_points" and "no_page_break_in_points" pair of instructions.

The substitution of text is one of the two keys to being able to create site-specific documents from a single source document.  The first step in this is to define the text to be substituted, while the second step is to include references to this text throughout the document.

To define the text to be substituted, use the string "^[substitute", followed by a space, then the key string used throughout the source document (which must not include a space), then a space, then the text to be substituted for each occurrence of the key string, then the end-of-line (carriage-return line-feed).  The key string must start with the escape character to distinguish it from regular text, and is best started with a pair of escape characters to distinguish it from word processing instructions.

So, for example, consider the specification of the site name.  Typically, you would include, in the header file for that site, the following:

  ^[substitute ^[^[site_name VersaCold Cold Stores Laverton II

Now, throughout the source document, where ever you would have normally referred to the name of the site, you would now include the string "^[^[site_name".  For example, the source document may contain:

  This manual describes the operation of the ^[^[site_name
  Movement Controller.


  The software controls the Heavy-Unit-Load Conveyors and
  six cranes which comprise the load store.

After processing the source document, the resulting output files will contain something like:

  This manual describes the operation of the VersaCold
  Cold Stores Laverton II Movement Controller.


  The software controls the heavy-unit-load
  conveyors and six cranes which comprise the load
  store.

The conditional compilation is second, and more important, of the two keys to being able to create site-specific documents from a single source document. The first step in this is to name the elements the document is to support, while the second step is to test whether these elements have been named before including the relevant sections from the source document.

To name the element, use the string "^[define", followed by a space, then the name of the element (which must not include a space).

So, for example, consider the element of the document relating to cranes. Typically, you would include, in the header file for that site, the following:

  ^[define cranes

As the word processor is only expecting to find the element name in places where normal text is not expected, there is not necessity to precede the names with a pair of escape characters.

The simplest way to use the element name is with the "if" construct.  At the start of a section, use the string "^[if", followed by a space, then the element name, then the string, "^[level", which introduces the new section, followed by the level number and section name (refer to the section titled: "Partitioning Your Document"). This will result in the processed document excluding this section, along with all its subsections, unless the element name has been defined.

For example, the subsection on cranes might start as follows:

  ^[if cranes ^[level 2 Crane Status and Control

  ^[screen_number IssueCraneCommands
  After selecting "Crane Status and Control" from the
  Operation Menu the crane status and control window will
  be presented.

Sometimes, this simple approach is not sufficient.  This is typically the case where there are options within the section.  For example, this software package comes in two styles, one built around the Microsoft DOS environment, and the other built around the X-Windows environment.  To accommodate this, we use the "^[if_block" string, followed by a space, then optionally followed by an exclamation mark, "!", to mean "not", followed by the element name, followed by the end-of-line (carriage-return line-feed).  All subsequent text will be included or excluded, depending on whether the element name has been defined and whether the exclamation mark was used or not, until the string "^[end_if_block" is encountered.  The "^[end_if_block" string should appear on a line by itself.

For an example, consider the following:

  ^[if_block x_windows
  Immediately above the location details,
  ^[end_if_block
  ^[if_block !x_windows
  Immediately below the lower legend,
  ^[end_if_block
  the restriction details are presented.

Had "x_windows" been defined, after processing the source document, the resulting output files will contain something like:

  Immediately above the location details, the
  restriction details are presented.

Whereas, had "x_windows" not been defined, after processing the source document, the resulting output files will contain something like:

  Immediately below the lower legend, the
  restriction details are presented.

The stand-alone word processor manual is produced from the main source file, "technica.wpi", by providing its own header file, "wp.wph", that sets definitions that are tested within "technica.wpi" to set substitutions that reduce the level numbers for the word processor section so that its major subsections are promoted to the major subsections of the whole document.  If you find this of interest, please refer to the file, "wp.wph", where it defines "wp_only" and to "technica.wpi" and see how it uses "wp_only" to discard all but the word processor section and to promote its subsections.

This word processor does not offer a wide variety of fonts, and other "pretties" but instead concentrates on getting the important part of the job done. However, some text presentation options are essential.

This word processor supports the following text presentation options:

• bold
• compress
• italic

The string "^[bold" is used to mark the start of the range of text to be rendered bold, while the string "^[end_bold" is used to mark the end of this range.

The string "^[compress" is used to mark the start of the range of text to be rendered more compressed, while the string "^[end_compress" is used to mark the end of this range.

The string "^[italic" is used to mark the start of the range of text to be rendered in italics, while the string "^[end_italic" is used to mark the end of this range.

When using multiple options it is best to end them in the reverse order to which they were selected, so that if "bold" is enabled, then "italic", then you should disable "italic" before disabling "bold".

It is an error for any of these text presentation options to be still in force at the end of the document.

Normally any amount of horizontal white space is compressed into a single space, and all non-blank lines are treated as a single line to be broken up into the lines of a single paragraph, while one or more blank lines, equivalently, delimit a paragraph, yielding a single blank line between the paragraphs.

This is normally what you would want to happen, however, on odd occasions, you will want to be able to place characters in explicit locations.

To do this, use the string "^[literal".  You would normally place an end of line at this point so as to have a reference point from which to space your text.  Macros will continue to be recognised throughout the text from this point.

In placing your text, it is best to not extend too far across the line, as the document may need to be rendered on a narrow medium at some time.

After the text which is to be placed explicitly, include the string "^[end_literal".

An example would be:

  Include the following statements in the system configuration
  file "C:\CONFIG.SYS":^[bold^[literal
            DEVICE=C:\DIGI\XIDOS5.SYS
            BUFFERS=20,0
            FILES=30
            LASTDRIVE=C
            FCBS=4,0
            STACKS=9,256^[end_literal^[end_bold

After processing the source document, the resulting output files will contain something like:

  Include the following statements in the system
  configuration file "C:\CONFIG.SYS":

            DEVICE=C:\DIGI\XIDOS5.SYS
            BUFFERS=20,0
            FILES=30
            LASTDRIVE=C
            FCBS=4,0
            STACKS=9,256

Whereas, had the "^[literal" and "^[end_literal" instructions been omitted, after processing the source document, the resulting output files will contain something like:

  Include the following statements in the system
  configuration file "C:\CONFIG.SYS":
  DEVICE=C:\DIGI\XIDOS5.SYS BUFFERS=20,0 FILES=30
  LASTDRIVE=C FCBS=4,0 STACKS=9,256

Note that when rendering the document under Netscape Communicator, in spite of specifying pre-formatted text and true-type font, the text is still not accurately positioned.  The Microsoft Internet Explorer seems to be more well-behaved in this respect, as is the printed form of the document and the rendering of it via the Movement Controller's help system.

Many of the windows presented by the Movement Controller software are basically text screens.  In the DOS system, these screens are 25 lines by 80 characters.  In the X-Windows system, the screen size is variable.  As a result, we present all text screen dumps in the 25 x 80 arrangement.

Screen dumps are started with the string "^[screen" on a line on its own, followed by the 25 lines of the screen dump, followed by the string "^[end_screen" also on a single line.

Upon processing, the characters of the intervening 25 lines are "compressed" and placed within a box containing 25 lines by 80 characters.  The distance, of each character from the left of the column in the source document, determines where it will be placed relative to the left side of the box. As a result, there should be no characters placed beyond column 80 in this portion of the source document.

Because the characters are compressed, the full screen width of 80 characters will be presented even though normally fewer characters can be accommodated across a page.

When presenting these in HTML, a blue background is provided, however Netscape Communicator does not extend the blue background to the full 80 columns unless the text also extends that far - not just spaces.  Also Netscape has trouble presenting some of the extended IBM character set.

The paragraph immediately preceding the "^[screen" line, should be brief and serve no other purpose than to introduce the screen dump.  This is because both this paragraph and the screen dump will not be presented by the Movement Controller's help system.

In order to present full graphical screen dumps, or other images, use the string "^[extra_page", followed by a space, followed by the filename of the ".gif" file (without the extension), followed by another space, then the caption of the image, followed by the end-of-line (carriage-return line-feed).

When processing this for printing, the output files will contain some substantially blank pages, save the page title and the caption for the image. It is intended that these pages be fed into the printer again to have the image printed on them via some other software.  There will be a note in the output, at the position of the "^[extra_page" instruction, to refer to the image on the following page.

On the other hand the HTML file will reference the nominated ".gif" file so that, provided the file exists, the HTML rendering program will present the image in the document in its proper position.

It is intended that the ".gif" file exists in the directory dedicated to the site, so that relevant images may be presented for the site.

When producing the RTF file, you should use a third-party's word processor to save the ".gif" file as an ".rtf" file with the same name stem as the original ".gif" file.  These ".rtf" files will be referred to as subdocuments of the RTF file being produced, and be presented on the page following their reference with the appropriate page title and picture caption.

The page formatting instructions affect the printer output files only.  These instructions are typically included at the top of the source document, each on a separate line.  The instruction strings are:

• "^[lines_per_page"

  The number of line on a page, including the top and bottom margins.  Default value is 63.

• "^[left_margin   "

  The blank characters to leave at the left of the page.  Default value is 10.

• "^[right_margin  "

  The number of columns across the page including the left marign.  Default value is 75.

• "^[top_margin    "

  The number of blank lines to leave at the top of the page.  Default value is 10.

• "^[bottom_margin "

  The number of blank lines to leave at the bottom. The difference between the number lines per page and the bottom margin is the only value of importance.  For example, if there are three lines which must be left at the bottom of the page it make no difference whether the number of lines per page is 66 and the bottom margin is 3 or the number of lines per page is 63 and the bottom margin is 0.  Default value is 0.

Each of these strings is to be followed by a space, then the specification of the quantity.  For example, the source document might start with the lines:

  ^[lines_per_page 60
  ^[left_margin 10
  ^[right_margin 75
  ^[top_margin 0

When producing an RTF document, these values are discarded.  Instead, the margins are specified relative to the edges of the paper, in twips (1440ths of an inch). In addition, the number of columns and rows are also to be specified, and the point sizes for the regular and condensed fonts. on a separate line.  The instruction strings are:

• "^[rtf_n_columns           "

  The number of characters to be printed across a single line, excluding the left and right margins, for an RTF file. Default value is 85.

• "^[rtf_n_lines             "

  The number of lines to be printed on a page, excluding the top and bottom margins, for an RTF file.  Default is 63.

• "^[rtf_left_twips          "

  The number of twips (1440ths of an inch) of paper to be left at the left of a page.  Default is 1008 (0.70inches, 17.8mm).

• "^[rtf_right_twips         "

  The number of twips (1440ths of an inch) of paper to be left at the right of a page.  Default is 1008 (0.70inches, 17.8mm).

• "^[rtf_top_twips           "

  The number of twips (1440ths of an inch) of paper to be left at the top of a page.  Default is 850 (0.59inches, 15mm).

• "^[rtf_bottom_twips        "

  The number of twips (1440ths of an inch) of paper to be left at the bottom of a page.  Default is 850 (0.59inches, 15mm).

• "^[rtf_regular_font_size   "

  The size of the font used for most of the printing.  Default is 20.

• "^[rtf_compressed_font_size"

  The size of the font used for compressed printing (whether implicitly requested for ASCII screen dumps, or explicitly requested).  Default is 13.

Each of these strings is to be followed by a space, then the specification of the quantity.  For example, the source document might include the lines:

  ^[rtf_left_twips 850
  ^[rtf_right_twips 850
  ^[rtf_top_twips 850
  ^[rtf_bottom_twips 850

These instructions are expected to reside in the printer configuration file.  The first instruction is the printer initialisation instruction, which starts with the string "^[substitute ^[initialise_printer", followed by a space, then followed by the printer initialisation string.  Typically this string will contain escape sequences to select portrait mode, set the font, the print weight and so on.

This string is included at the start of each printer output file.  If no initialisation string is specified, then no initialisation string is included in the printer output files.  This is as would be required for the early IBM dot-matrix printers originally supplied for IBM PCs.

The other instructions for the printer, to be included in the printer output files, are the instructions to enable and disable the text presentation options "bold", "italic", and "compress".

You can use the "^[substitute" instruction, followed by a space, followed by one of the instructions to enable or disable a text presentation option, followed by another space, then followed by the string required by the printer to achieve this, followed, finally, by the end-of-line (carriage-return line-feed).

If you do not include these instructions, the default behaviour is to produce output suitable for a printer in IBM emulation mode; that is a printer emulating the behaviour of an early IBM PC dot-matrix printer.

For example, the printer configuration file for an HP DeskJet might include the following lines:

  ^[substitute ^[initialise_printer ^[&126A^[&k0G
  ^[&s1C^[&l0O^[(10U^[&l66P^[&l3E^[&l63F^[*o1M^[(
  s0P^[(s0S^[*v1S^[(s3T^[&l6D^[&l8C^[(s12V^[&k12H
  ^[(s10H
  ^[substitute ^[compress ^[&k8H^[(s15H
  ^[substitute ^[end_compress ^[&k12H^[(s10H
  ^[substitute ^[bold ^[(s7B
  ^[substitute ^[end_bold ^[(s0B
  ^[substitute ^[italic ^[(s1S
  ^[substitute ^[end_italic ^[(s0S

Note that in the above example, the first four lines should be a single line with no intervening spaces.

In this example, the escape sequences for "^[initialise_printer" select the following options:

• ISO A4
• CR=CR, LF=LF, FF=FF (this is essential)
• No end of line wrap
• Portrait, not Landscape
• PC-8 font (this calls up the characters used in the BIOS of IBM compatible computers to correspond to the extended ASCII codes from 128 to 255, and is essential for most of my own manuals)
• 66 lines per page
• 3 blank lines at the top of the page
• 63 lines of text, leaving no blank lines at the bottom of the page
• Normal presentation, not draft
• Fixed character pitch (this is essential)
• Upright style - not italic (this is essential)
• True black
• Courier
• 6 lines per inch
• 8/48 inches per line
• 12/72 point size
• 10 characters per inch

The page setup must allow the printer to fit a page of output from the word processor on a single printed page.  The number of lines down a page, and characters across a page can be specified for the document.  I, typically, specify 60 lines of 65 characters, beyond a margin of 10 characters, giving a total width (or right margin) of 75 characters.  My manuals also include some wider lines for which the "^[compress" escape sequences are called in to allow these to fit in the same physical space.

The escape sequences for "^[compress" select 16 characters per inch, while those for "^[end_compress" return to 10 characters per inch.