[[page created automatically from word-processed document; for original see: Postscript version]]
.if \n(.g \{\ .de BM .sp \$2 .. \} .de np .. .de up .. .de Dl .if t \$1\l'|0\(ul'\l'|0\(rn'\$2 .if n .I \$1 \$2 .. .de xs \!.ss 27 \!.cs R 27 \!.cs B 27 .cs R 27 .cs B 27 .. .de xe \!.ss 12 \!.cs R \!.cs B .cs R .cs B ..
GUIDE user manual
P.J. Brown Computing Laboratory The University CANTERBURY Kent, CT2 7NF
C P.J. Brown 1985
Sixteenth impression, April 1995 .pn 1 .up
Chapter 1 Basic concepts
It is a common practice to store explanatory documents in computer files and to read them from a computer screen. Such documents, however, have a notorious defect: they do not cater for the needs of different readers. Some readers want every detail, others want an overview; some readers want a wealth of tutorial examples, others find such examples a distraction; some readers wish to use documents for reference purposes, others want a complete description. Guide is a system to help all these readers. It provides a simple way for people to display information in a selective way, and for authors to create material that can be so displayed. In short, Guide aims to make computer-based documents more pleasant to read than paper-based ones, rather than less pleasant as has often been the case in the past.
Guide is not one of those systems that offers you ten thousand different facilities, if only you can work out how to use them. Instead the reader is presented with a few simple and general facilities. The facilities used by authors for creating material are, however, more elaborate.
Information for Guide to use is stored in Guide source files. Clearly the nature of the source files provided will vary according to the organization in which Guide is used. Often there will be a wide range of available source files, covering such diverse topics as:
A typical Guide session proceeds as follows. Initially you, the reader, specify the source file(s) that you want to examine. These are copied into Guide's internal storage -- a process called loading -- and they form your current source. Having done its loading, Guide displays a document, which consists of material extracted from the source. Initially the document normally consists of a brief summary of the information available. You then request certain parts of the document to be expanded to give you further detail. You continue doing this until you have built a document containing just the details you want to read, no more and no less. In short you have created a document exactly tailored to your own needs.
Often the document that you build with Guide will only be of transitory interest. Assume, for example, that a computer command is not doing what you expect: you want information about how it works, so you peruse a Guide source file that describes the command. In this case you will read your document as you create it on the screen, but, once you have read all the information you need, you will not want to preserve the document. On other occasions you may find that your document is of lasting interest and worth preserving in a file.
The Guide system has been designed to be simple and natural to use, and the average user will never need to read this complete user manual. Instead she will start by having a session with a demonstration source, and after ten minutes or so will be using Guide in earnest. To start Guide type the command name guide and follow it with an argument list, which specifies the name(s) of the source file(s) to be loaded into Guide. On the .UX system a Guide demonstration source file is in help (within a directory used for public Guide source files) and can be set going by means of the command
.lg 0 guide help
There is a freely available version of Guide called guide_reader; this is identical to Guide itself except that it lacks authorship facilities. When authors create Guide material and wish to issue it to sites that may not have Guide, they can include guide_reader with their issued material.
The purpose of this manual is to give a complete description of Guide: it is therefore suitable for those who do not have access to a demonstration, for those who prefer to read before they act, or for those who need a manual for reference.
This manual applies to the UNIX implementations of Guide developed by the University of Kent at Canterbury. These run under windowing systems such as X and SunView. Implementations of Guide also exist on PC and Macintosh computers. They have been developed by OWL, following a contract with the University, and are now sold by a Seattle company called InfoAccess. Given their different environment, InfoAcess's versions are different in detail from the university's.
All implementations emanating from the University of Kent are essentially the same, and differences only arise because of hardware variations and variations in operating systems or windowing systems. These differences are described in local documentation, which you can read by applying Guide to a source file called local.guide. Like all UNIX utilities, Guide has a manual page; the manual page, which is complementary to this manual, describes the UNIX interface, including such matters as switches and environment variables.
This manual assumes a graphics screen and a pointing-device with two or three `buttons', which are called button A, button B and, if pre-setting (q.v.) is to be allowed, button C. (Alternatively these can be represented by a single button that can be clicked once, twice or three times.)
As we have said, source files can cover a diversity of information. This diversity reflects the wide range of uses of Guide:
Often it is used to achieve a mixture of the above.
Like most modern software, Guide is screen-based, that is it provides a convenient user interface by displaying a whole screenful of information, menus, etc. This Guide `screen' will normally be a sub-part (a window) of the real screen. A document is treated as if it were one continuous page. Often, however, a document will be too big to fit on the screen; if so the screen can be considered to provide a frame-of-view covering part of the document. You can move the frame-of-view so that you can look at any part of the document you wish.
On the top part of its screen Guide displays a menu of commands; on the right-hand side it displays a thumb-bar, used to move the frame-of-view around the document. (Within the menu, commands that are not currently valid are dimmed -- on a monochrome screen they are shown in grey.) The rest of the screen -- called the document area -- shows the document itself.
When you interact with Guide, you control it exclusively by moving a cursor round the screen to point at what you want, and then selecting this. Selection is done by clicking button A on the pointing-device. You can select a menu command, a position in the thumb-bar (in order to move your frame-of-view) or a position in your document. As we shall see, documents contain a mixture of text, pictures and buttons. A button on the screen is a natural extension of a button on the pointing-device: if you point at a screen button and click a button on the pointing-device it is as if you pressed the screen button that you are pointing at. Indeed a screen button is just like a menu command: if you select it something happens.
This simple interface helps minimize errors. If you do make a mistake Guide will simply beep at you, and refuse to carry out your instruction.
The thumb-bar is part black and part white,
and shows the position of the current frame-of-view within the seen document,
i.e. the parts of the document that have been seen so far.
(In this manual we use the terms `black' and `white' as if you were using
a monochrome display with black as the foreground colour. All the Figures
have been produced on such a display.) The black part of the thumb-bar indicates the
current frame-of-view and the white part represents the other parts of the
seen document.
Thus if the thumb-bar appears as
.sp .8
.PS
B1: box wid 1.15i ht 0.15i
B2: box wid 1.15i ht 0.13i with .w at B1.e
B3: box wid 1.15i ht 0.15i with .w at B2.e
line from B2.sw + (0,0.12i) to B2.se + (0,0.12i)
line from B2.sw + (0,0.11i) to B2.se + (0,0.11i)
line from B2.sw + (0,0.1i) to B2.se + (0,0.1i)
line from B2.sw + (0,0.09i) to B2.se + (0,0.09i)
line from B2.sw + (0,0.08i) to B2.se + (0,0.08i)
line from B2.sw + (0,0.07i) to B2.se + (0,0.07i)
line from B2.sw + (0,0.06i) to B2.se + (0,0.06i)
line from B2.sw + (0,0.05i) to B2.se + (0,0.05i)
line from B2.sw + (0,0.04i) to B2.se + (0,0.04i)
line from B2.sw + (0,0.03i) to B2.se + (0,0.03i)
line from B2.sw + (0,0.02i) to B2.se + (0,0.02i)
line from B2.sw + (0,0.01i) to B2.se + (0,0.01i)
.PE
.sp .8
-- we have drawn it on its side to save space --
then the frame-of-view you are looking at represents the middle third of the
seen document. If you then select a point, say, four-fifths the way along the
thumb-bar then your frame-of-view will be centred four-fifths the way through
the seen document.
If you wish to advance the frame-of-view so that it immediately follows
the current one (i.e. the equivalent of turning a page in a book),
it is best to use the \f3Down and \f3Up\fP commands in the menu rather than the thumb-bar.
These commands, together with other commands in the menu, will be described in
Chapter 5.
.sp .5
Figure 1: a Guide screen
Figure 1 illustrates a sample Guide screen, which shows the initial document that is displayed after a source file called rm, which explains the rm UNIX command, has been loaded. Within the document you can see buttons labelled `More' and `Example', which are displayed in bold. In addition the underlined words unlink and syntax are also buttons, though of a different type, as we shall explain when we come to `glossary-buttons'. The thumb-bar in Figure 1 is all black since the document is smaller than the screen and thus the frame-of-view encompasses the whole document. For the same reason the \f3Down and \f3Up\fP commands are dimmed.
With Guide you can not only read documents: you can also change them to fit your own needs. You can make as many additions and corrections as you like. Thus if your document describes how to mend a machine, you might care to add the comment `On my machine this knob is just under the red security label', and you might change the phrase `quoting your serial number' to `quoting number AB/294'. To perform edits you first select the position in your document where you want the change to be made; Guide then displays a small marker-bar on the right-hand side of the character you have selected. Having done this you can type characters on the keyboard in order to make the requisite change. We discuss editing in Chapter 2.
A document can include three types of button: replace-buttons, glossary-buttons and action-buttons. The names of the buttons can be any string of characters and/or pictures; it is obviously sensible for authors to choose natural names, e.g. a button that is replaced by an example should have a name such as `Example'. By default, replace-buttons are displayed in bold in the same way as the menu buttons, glossary-buttons are underlined, and action-buttons are displayed in bold with a line top and bottom. We shall first explain replace-buttons.
If you select a replace-button it is replaced by the text (and/or pictures) associated with that button. Thus if you select Example it will be replaced by an example. Figure 2 shows the effect of selecting the More button in Figure 1 which follows the word `DESCRIPTION'.
.sp .5
Figure 2: result of selecting a More button
Notice how the replacement of More itself contains further replace-buttons, which can be used if the reader wants still more detail. Typically Guide documents are first presented as a summary so that you can expand the parts you want by selecting appropriate replace-buttons. If you do not like the replacement of any button you can, at any time, undo it by pointing anywhere within its replacement and clicking button B. The original replace-button then reappears. You can browse through a document in any way you like by selecting whichever replace-buttons you wish. If there is anything you do not like you can simply undo it and, provided it is part of a replacement, it will disappear. In some cases you might wish to tailor a document so that it contains just the replacements you want, and then save this as your own personal document. You may, moreover, put your own edits in the document before saving it so that the document is truly tailored for you.
In some documents, the author will have embedded one or more replace-buttons inside an enquiry. A simple example of an enquiry, is
Do you want to know More?
You use replace-buttons within enquiries in the normal way. The only difference is that the entire enquiry is replaced by the replace-button's replacement (and similarly the entire enquiry re-appears if the replacement is undone).
Enquiries are most often used when there is more than one alternative response, e.g.
Is the flower BLUE, YELLOW or RED?
You can use Guide to display several documents at the same time by using a `split-screen' display. In this case the document area is divided into several different views. Each view is entirely independent of the others. Figure 3 shows a screen containing three separate views; the thumb-bar is divided into three separate thumb-bars (separated by small square striped areas), one for each view. The middle view contains a document that is a mixture of text and pictures; what is seen is part of a picture.
.sp .5
Figure 3: a Guide screen divided into three views
Generally Guide users only create one view. Views are, however, important when glossary-buttons are used. Glossary-buttons have many uses but the most popular one is for words or phrases that the reader may not understand, and may therefore want to see an explanation. When a glossary-button is selected, a definition of its meaning is created and placed in a special view called the glossary-view. Figure 4 shows the result of selecting the glossary-button `syntax', which appears in Figure 1.
.sp .5
Figure 4: the result of selecting the glossary-button `syntax' in Figure 1
When the first glossary-button is selected, Guide creates a new view and designates this the glossary-view. (Strictly speaking, we should pepper this paragraph with the word `normally', since, as will be explained later, certain exceptional kinds of glossary-button do not use the glossary-view.) The difference between a replace-button and a glossary-button is that replacement of the former overwrites the original button whereas the replacement of the latter is put in a separate place (normally within the glossary-view) and the original button still remains. As more and more glossary-buttons are selected, more and more definitions are added to the glossary-view. These definitions are inserted in alphabetical order (as defined by the ASCII encoding -- upper-case letters and lower-case ones are not, however, differentiated) so that the glossary-view acts as an alphabetical glossary of all the terms for which you want definitions. When a glossary-button is selected, the frame-of-view on the glossary-view is automatically positioned so that the appropriate definition is at the top of the frame-of-view. A document may, and often does, contain several occurrences of the same glossary-button. Thus a document on car maintenance may have several occurrences of the glossary-button carburettor . It is, moreover, possible for several glossary-buttons -- which may even have different names -- to share the same definition.
Although the glossary-view has this special interaction with glossary-buttons, you can still use it just as any other Guide view. Thus you can edit it, expand buttons within it, move your frame-of-view around it, etc. If you undo a definition of a glossary-button its definition disappears from the display (though actually the definition remains present but invisible and will spring to life again if the original glossary-button -- or another glossary-button using the same definition -- is selected). If you undo all the definitions in the glossary-view, the glossary-view itself will disappear.
The mechanism of glossary-buttons can be used much more generally than just for definitions of terms. Other uses are
The definitions corresponding to glossary-buttons are given by special replace-buttons that not only define their own replacement, but also the replacement of any glossary-button of the same name. In the next Chapter we shall explain how definitions are created.
The third type of button, the action-button, gives authors a way of exploiting Guide's programmability features. Actions may involve commands to the Unix shell, such as starting up a new application that runs in a new window, or commands to Guide itself, such as loading new files. Each time an action-button is selected, the corresponding action happens. There is no notion of a `replacement' for an action-button. Examples of action-buttons are .Dl Start-up and .Dl Re-load .
Guide does not have any predefined requirements about screen size. Indeed its screen size can be dynamically changed while it is running.
On implementations where the Guide screen is actually a window within the real screen, Guide normally creates a new window when it begins a session. This window can be as large or small as desired (subject to certain minima). Thus if you are using Guide to find information about a computer program you are currently using, you might make the window containing Guide occupy a quarter of the screen, with the rest of the screen devoted to the program you are using. Under most windowing systems, a window can be changed in size at any time; if this happens, Guide will automatically reformat the document to fit the size of its screen, and thus you can make this larger or smaller to suit your immediate needs.
Guide automatically lays out text so that lines are filled. If a word does not fit on the current line Guide automatically starts a new line. Thus the unreadable breaks in words -- or inelegant hyphenation -- found in some text display systems are avoided in Guide. (A Guide `word' is defined as anything that ends with a space, tab, form-feed or newline -- thus `123' and `+++' count as words.) The only time that Guide may break a word arises when a word is over two-thirds the width of the screen.
Like most screen-based software, Guide caters for variable-width fonts. It is possible to use any number of fonts (and/or colours) within a document: Guide provides a mechanism (see contexts in Chapter 4) that tries to capture the logical nature of material rather than just the font that is attached to it.
(This Section describes a specialised use of Guide, and you may do well to skip it; all you need to know for the moment is that the standard version of Guide supports a preprocessor that converts UNIX manual pages into Guide format.)
Guide is useful for viewing information in databases. Here the source will not consist of individual and separate files, but will consist of material extracted from a structure of inter-related information, the exact representation of which the reader does not understand and does not need to understand.
To cater for these applications, Guide makes provision for a preprocessor to be attached to it. Preprocessors vary between implementations of Guide, depending on the databases that need to be viewed. Some implementations have several alternative versions of Guide, each with a different preprocessor. Details of the available preprocessors will be found in local documentation. As we have said, the standard preprocessor deals with the `database' that consists of the UNIX manual pages. many implementations just provide this standard preprocessor.
Preprocessors work on the argument list supplied within the command to enter Guide or within the \f3New command (q.v.). Normally items on an argument list are names of source files. However, with a preprocessor working on the argument list, an item need not directly name a source file: instead it might be used by a preprocessor as a key to finding or creating the source material. Let us assume, for example, that one item of the argument list is the word `Portugal'. Then possible actions of preprocessors are:
A particular preprocessor can support any combination of the above kinds of action. It could even perform activities such as compiling programs or receiving network mail. Some items on argument lists might be treated by a preprocessor as options rather than names. For example an option `-finance' could be used to mean that subsequent items on argument lists were to be taken from a database called finance.
As well as applying to source files input to Guide, the preprocessor also applies to the files that contain definitions of glossary-buttons. These, too, can come from a database.
To summarise, preprocessors apply to all input to Guide from the filing system, and can be used to provide a friendly interface to a Guide user who wants to view a complete body of data. Preprocessors do not apply to output from Guide written back to the filing system. .up
.cs R 27 .cs B 27 .. .de dE.cs R .cs B .. \} .np
Chapter 2 Editing
Traditionally, documents (whether electronic or on paper) have been written by an author, and are then perused by readers. Guide breaks down this strict demarcation between author and reader -- to the benefit of both. The key to this is that the reader can change his document.
If you change your document not only does Guide update the document as displayed, but it also makes the same changes in the underlying source. Having made changes, you can save the new source, either overwriting the original source file(s), or creating new source file(s). (Normally the author of a source file will attach protection attributes to his file so that only he can overwrite it.)
The way that you build a source if you are the original author is as follows: you create a document (either by editing an existing source or from scratch) and, when you are satisfied, you save the new source you have created. Hence:
If you want to use Guide to build a new source from scratch, you start Guide with a null argument list -- and hence no source file.
A source is a mixture of text, pictures and information about the structure. The structuring information covers such matters as:
Pictures cannot be edited within Guide, but the other two components of the source (text and structure) can. Guide offers two types of editing:
When you perform structural editing, you need to view the underlying structure. To allow you to do this, the Guide menu provides an \f3Author command. This command switches the screen to author-display; in author-display you see some extra control characters that delimit the structure of your document. To switch back to the normal reader-display, where these control characters are unseen, you use the \f3Reader command ( -- this appears in the menu when you are in author-display). As an author you are recommended to use author-display even when all your edits are textual. Otherwise you might, for example, find it hard to tell whether text you are inserting forms part of a replacement or not.
Author-display gives extra detail, and the act of undoing sometimes reveals detail that would otherwise be hidden. Thus we shall, in this Chapter, come across some instances where undoing when in author-display behaves rather differently from undoing when in reader-display.
Before you perform any editing the marker-bar must be placed. If the marker-bar goes out of your frame-of-view -- for example because you use the thumb-bar to look elsewhere in your document -- then its position is forgotten by Guide. Thus all editing must be within the current frame-of-view. The only exception to this occurs when you insert extra lines after the last line in a frame-of-view; in this case the marker-bar does not disappear out of the frame-of-view but instead Guide automatically scrolls to the next line.
If a pair of words such as `cross roads' happens to be displayed so that `cross' is on the end of one line and `roads' is at the start of the next, then the space between the two words appears immediately after the first word (i.e. at the very end of a line). The reader cannot see this, but it is there to allow the marker-bar to be placed on the space so that it can be edited.
Textual editing is simple: you just type characters and they are inserted in your document at the position where you have put the marker-bar. If you type the DELETE key this deletes the character at the marker-bar. (The only other special character is CONTROL+A, which inserts the contents of the cut-buffer when Guide is running under a window system that supports cut-and-paste.) You cannot insert or delete the control characters that represent the structure; these can only be manipulated using structural editing.
When you type text into Guide remember that, if you plan to save the revised source and use it again, the screen-size may be different next time. In particular the number of characters on a line may change. Therefore only type the newline character if you really want it. Normally you should type newlines at the end of paragraphs of text but not within them. Within a paragraph you should use spaces to separate words and leave Guide to make the line breaks.
Guide supports tab characters, and has tab positions that are eight spaces apart, right across a line. If a tab takes the text to position N, say, then all subsequent lines are indented to position N until a newline is reached in the source. This allows you to indent paragraphs (provided you have followed the rule that newlines should not occur within paragraphs). Thus if you type
(a) tab This is the first case, which ... more text ... newline
this will be displayed as
(a) This is the first case, which ...
more text
...
See Appendix A for more details.
Guide has the rule that if a replace-button has a null replacement, then, when the replacement appears, the marker-bar is automatically made to mark it. (Otherwise the reader would see nothing at all. Similarly if the source itself is null Guide automatically puts the marker-bar at the start.) Moreover, when in reader-display, a null replacement is represented by a special `null marker', consisting of a small circle with a cross within it, shown in reverse-video. The null marker gives something to select if it is desired to undo the replacement.
This can be exploited to make Guide useful for applications akin to form-filling. An example is the `personalized' circular letter. Part of this might read
Dear FILL THE NAME HERE,
Because I regard you as my greatest friend, I would like to ask you a
small favour: could you lend me the tiny sum of WHAT HE MIGHT GIVE ...
If the user selects the replace-button FILL THE NAME HERE, which we assume has a null replacement, the replace-button disappears and the marker-bar appears in its place. Characters typed by the user -- in this case a person's name -- are then inserted at this point. When the user has typed the name, and all the other replacements, his document is the required personalized circular letter.
Although, as the above example shows, replace-buttons can usefully have null replacements, it is not sensible for a glossary-button to have a null definition -- if an invisible definition appears this will not help the reader; hence Guide gives a warning message in this case to alert the reader to what is an error of authorship.
Sometimes you will wish to take a block of material and delete it, or move/copy it to another place. Guide provides the \f3Block-edit menu command to perform this type of editing. Before using this command, place the marker-bar at the start of the block to be edited. The \f3Block-edit command initiates a dialogue which allows you to define what editing you want. The block to be edited may cross several frames-of-view; it cannot contain incomplete Guide constructs: it would be absurd, for example, to move a button and half of its replacement, leaving the other half in its original place. It is normally best to use \f3Block-edit when in author-display, so that you can see where Guide constructions begin and end. Sometimes it is useful to perform a move in two stages: firstly to move to an `obvious' place, such as the end of the source (or to the cut-buffer); secondly to move this to the destination. Such a two-stage process is particularly suitable for material deep within Guide structures.
In Chapter 1 we explained buttons from the point of view of a reader who selected them. As an introduction to structural editing, we shall explain more about where the replacements of buttons come from. There are actually three kinds of replace-button:
Usage-buttons use the same mechanism (explained below) to create their replacements as glossary-buttons do. These two are called dependent buttons since they depend on other material for their replacement. The difference between a usage-button and a glossary-button is that the replacement of the former goes in place of the button, whereas the replacement of the latter appears separately.
If you point at a button and hold the mouse-button down, Guide will show, by adjusting the cursor-pattern, the type of the button. This feed-back is especially helpful to authors. Another aid that helps authors identify types of buttons is that, when in author-display, all definition-buttons are underlined (as well as appearing in bold as is normal). Authors can therefore find their definition-buttons quickly. There is also feed-back on undoing: this consists of a pop-up menu giving the names of all the replace-buttons encompassing the current position; a second level of feed-back shows the scope of each such replacement. All this is an invaluable aid to prevent Guide users getting lost.
Guide has no restrictions on the names used for buttons, and indeed the same name can be used on several different local-buttons. When you create a button you specify its type, i.e. whether it is a definition-button, local-button, usage-button, glossary-button or action-button.
As examples, a source might contain the following buttons:
Having explained the principles, we can now cover the mechanisms whereby you create buttons. Your first act is to select the \f3Author command. You then see an additional menu, which has commands for creation of buttons, etc. These commands are described in Chapter 5. You also see the control characters that delimit the structure underlying your document. These control characters are represented by capital letters, shown in reverse-video so that they stand out. The letter representing the end of a construction is a mirror image of the one representing the start. In particular: .sp .3 .Gc "" E 16 marks the start of an enquiry. .sp .3 .Gc "" e 17 marks the end of an enquiry. .sp .3 .Gc "" B 4 represents the start of a button (glossary, action or replace) .sp .3 .Gc "" b 1 represents the end of a button. .sp .3 .Gc "" R 6 represents the start of the replacement of a local-button or of a definition-button. .sp .3 .Gc "" r 14 represents the end of such a replacement. .sp .3 .Gc "" C 8 represents the start of the replacement of a dependent button. .sp .3 .Gc "" c 15 represents the end of the replacement of a dependent button. .sp .3 .Gc "" P 18 represents the start of a `ghost' (see later). .sp .3 .Gc "" p 19 represents the end of a ghost. .sp .3 .Gc "" < 2 represents the start of the pre-set list (see later). .sp .3 .Gc "" > 3 represents the end of the pre-set list. .sp .3 .Gc "(A " T 7 "," on those implementations that support transcripts -- see later -- shows the presence of a transcript.)
Figure 5 shows an example of a Guide screen in author-display. In Figure 5 the marker-bar is positioned ready for editing. .sp .5
Figure 5: an author display of a document (the one shown in Figure 2)
Once you are in author-display you are free to create whatever structures you like. Remember that when, as an author, you create new enquiries and replace-buttons, this is a flexible facility which can be exploited in many ways. There are no pre-defined rules about the nature and relative size of enquiries and replacements. One example of an `unusual' enquiry is an enquiry that consists of a whole screed of text, ending with the replace-button PRECIS; if the user selects this replace-button, the screed of text is replaced by a short summary -- thus material is presented in a bottom-up way rather than the normal top-down way.
It is often useful for an author to write material that is seen by the author but not by readers. An example is a comment about a particular button. Guide supports a construction called a ghost, which achieves this end. On some implementations ghosts are displayed in a smaller font, so that they look different from the main text. Any Guide material can be included within a ghost; a ghost can therefore be used to `comment out' Guide material that the author feels is not currently suitable for showing to readers. Ghosts can also be used for `alien markup', i.e. material that is not used by Guide, but is valuable to some other tool that works on the same files. When a Guide user saves a file, ghosts are saved as well, thus preserving the alien markup. When a file contains alien markup, it will often be necessary to do some pre- and post-processing to aid communication with Guide, e.g. turning each piece of alien mark-up into a ghost. Ghosts can occur anywhere. The precise behaviour of ghosts is actually identical in author-display and reader-display; it is just that the painting of them on the screen is suspended when in reader-display. (This point can be important if automatically selected buttons -- see later -- within ghosts cause some Guide actions to occur.)
There are two types of definition-button: regional and world. When a world-definition is loaded it applies throughout the Guide source (i.e. any dependent button in any view can use it). In large hypertext applications involving many authors the use of world-definitions is likely to cause problems, since there may turn out to be two separate definitions which have been given the same name. (In fact the problems mirror many of the problems in writing programs that over-use global variables.) Hence Guide provides regional-definitions as an alternative to world-definitions. The scope of a regional-definition is the replacement that most closely encloses it. Regional-definitions take precedence over world-definitions, if they both have the same name. (Similarly, if two regional-definitions match the name of a dependent-button, the one with the smaller scope will prevail; if the scope is the same, the one further from the start of the source will prevail.) If a regional-definition is loaded in such a way that nothing encloses it then it will behave like a world-definition.
If you wish, the Guide source file can be an ordinary text file, not written as a Guide source and therefore containing no structuring. More to the point, structural editing in Guide can be used to improve such a text file by adding structure to it: you can load the text file, add replace-buttons to it so that certain details are only revealed when these buttons are selected, and then save the result as a new Guide source file.
The author needs to specify, for each dependent button, how its replacement is to be constructed. It is a principle of Guide that the machinations by which replacements are constructed should be invisible to the user. In particular the button-names that the user sees can be chosen by the author to be independent of the construction mechanism. Indeed it may even happen, for example, that two glossary-buttons that appear to the reader with entirely different names will lead to the identical material, or conversely that two glossary-buttons with the same name (e.g. help) and within the same Guide source will lead to different material.
The way Guide authors specify how the replacement of a dependent button is to be created is by means of an extension to the button-name. The extension, which is separated from the button-name by a tab, is only visible in author-display. (Button-names cannot, incidentally, themselves involve tabs.) As an example of an extension a glossary-button might appear in reader-display as
Lights will not work
and in author-display as
Lights will not work " "
alias battery check
Here the extension is `alias battery check'. When displayed on the screen, extensions are displayed in a fixed-width font to help distinguish them from other material. (Actually the `system font' as used in the command to call Guide itself is employed.) We will, however, use a normal font in this manual. The full syntax of an extension for a dependent button is:
[tab alias " " effective-name] [tab in " " filename] [tab replacement-definer]...
where the square brackets mean an item is optional, and the three dots means it can be repeated. We show fixed words such as `alias' in underlined form. The replacement-definer may be (a) a constructor, which says how the replacement is to be constructed, (b) an attribute, which gives the button some non-default property, or (c) a specification of an argument, as described in Chapter 3. The replacement-definer may be enclosed within `|' characters if it contains a tab; this prevents this tab being treated as a closing delimiter.
If the alias is absent then the effective-name is taken to be the button-name. The effective-name is used in matching a definition with buttons that depend on that definition; its use will be explained more fully in a minute.
When, as in all the examples up to now, there are no constructors, the replacement is constructed by searching for a definition-button that matches the effective-name. The search starts by seeing if the definition has already been loaded within the current source (the source encompasses all the current views); if this fails, it looks for the definition in a special file called the definitions-file. The default definitions-file is glossary.guide, but if a preprocessor is at work, it may search in other files as well as, or instead of, this default one. If in is used, the given filename is used in place of the definitions-file, e.g. `piston in car-parts'. When searching a definitions-file, Guide only searches for world-definitions; regional-definitions are ignored. Typically if a definition is used only in one source file it is placed in that source file; it is best made a regional-definition even if it applies to all the source file. If a definition is used in several different source files it is made a world-definition and placed in a definitions-file. A definitions-file, as its name implies, normally consists just of a sequence of definitions (world-definition, in fact), though it is treated by Guide like any other source file, and thus can contain any constructs it likes.
The following are the possible constructors that may be used to build up the replacement of a button:
syntax echo Syntax means: load-this-def
generates a replacement consisting of the string `Syntax means', followed by the definition of `syntax'.
An example of a composite button that uses several constructors is:
composite run myprogram load-def mydef do Find&Start "abutton"; Select
Constructors are also used to specify what action-buttons do. Normally an action-button uses a run or do extension. An action-button should have a null replacement; if it does not, an error message is given (which shows what the replacement is), and the replacement is ignored. This feature is, for example, valuable for shell-scripts which give unexpected error messages.
The only possible attributes are dynamic and append "." The dynamic attribute means that the replacement is to be re-evaluated every time the button is selected; this may be important if the button has a constructor that runs a shell-script to perform some action. The append attribute (which is only allowed on glossary-buttons) means that the replacement is to be appended to the current view, rather than added to the glossary-view.
We have referred above to the effective-name of a button. Usually this is just a string of characters, but it can involve the use of an of extension. The effective-name appears both on the definition and on the dependent buttons that use that definition. A definition-button could, for example, be
.ft B specification of XT19
The reader sees this as specification since the extension `of XT19' (which is preceded by a tab) is only visible when in author-display. However the effective-name of the definition-button is its full name. This is valuable to help authors make sure that names of definition-buttons are unique; it also allows the author to record extra information: `XT19' might, for example, be some internal reference number.
The full effective-name must be used by any dependent button that is to match the definition. Thus the following glossary-buttons would match the above definition:
specification of XT19
Effective-names can, in fact, have any number of of extensions, e.g.
.ft B A of B of C
The of extension is the only extension that is appropriate to definition-buttons.
The following are some examples of usage-buttons. (We assume `Fault action' and `Engine of GS/6' are existing definition-buttons.)
Fault actionEngine
of GS/6
alias Fault action
run ls
load chapter6
All of the above names would be valid as glossary-buttons. In addition the following is also valid as a glossary-button:
Engine " "
of gs/6 append
The following are suitable as action-buttons:
.Dl "Print it" " "
run myprint
run guide myfile&
do Find&Start "carburettor"
The last example uses the Guide \f3Find command, with its option to commence the search at the \f3Start, to search the current source for the first occurrence of the word `carburettor' and to re-focus the appropriate view accordingly if the word is found. Guide suspends its searching process when scanning the name of the button that initiated such a search; this prevents a button finding itself.
Usually a constructor will be a static string of text, as in all the examples shown so far. Occasionally, however, authors want a degree of dynamic change, e.g. a filename that depends on current circumstances. To facilitate this, Guide allows the following possible types of nested-elements within constructors:
Bodywork
load @{DIR}/chapter6
would, if the environment variable DIR had the value XYZ, load the file XYZ/chapter6. By convention @{<a-tab-character>} means a tab; this is a way of getting a tab into a constructor -- normally tabs act as terminators.
run @[ do Set "DIR="/Type the directory name:/]@{DIR}/xyz
The first nested-element (which has a null name and also produces a null replacement) prompts the user for a value and places this in the environment variable DIR -- the Set program-command is similar to the `set' command in the UNIX shell. The next nested-element uses the value of DIR. Thus if `pqr' is supplied as the value of DIR, the effect is `load pqr/xyz'. (Note that, since nested-elements are done first, the setting of DIR must be done within a nested-element -- and this nested-element must obviously come before the ones(s) that use DIR).
Nested-elements may be used freely -- they can even occur within other nested-elements -- except that they cannot be used to generate the name of a constructor (e.g. `load'). They can be used within the filename after `in', but are not recognized within the effective-name of a button (i.e. effective-names are fixed strings). The values of nested-elements are all evaluated before any of the constructors on a button are evaluated (this might matter when, for example, a Set program-command on a `do' constructor changes the value of an environment variable).
In the unlikely case that the value of a nested-element contains Guide constructions (e.g. buttons, ghosts, etc.), the value is taken as if it were saved in textual form when in reader-display (e.g. buttons are like ordinary text, ghosts disappear).
(This Section can be skipped on a first reading.)
In all cases the replacement of a dependent button can be any syntactically correct Guide material, i.e. it can involve buttons, sub-buttons, etc. Thus for example a shell-script, invoked by means of the run constructor, is allowed to generate Guide buttons (the author of the shell-script could find out about the necessary format by looking at a Guide source file).
When a usage-button is selected for the first time in the current session, its replacement is duly constructed. Thereafter, during the current session, the usage-button acts as if this constructed replacement were its local replacement. However if the source is saved, the constructed replacement is not saved. Thus when the saved file is used in a subsequent session, all usage-buttons will be re-constructed -- they may indeed be different from the previous occasion, especially if shell-scripts are involved or if the usage-button depends on some dynamic database.
When a glossary-button is first selected, similar rules apply to usage-buttons, except, of course, that the replacement does not overwrite the button. Instead a new entity called a temporary-definition is constructed, and placed at the appropriate position in the source (i.e. in the glossary-view unless the placement says otherwise). Temporary-definitions are just like ordinary world-definitions, except that they are normally temporary to the current session; they do not therefore represent something new to learn about. Indeed if the glossary-button is constructed by matching a definition, then the temporary-definition is an exact copy of the definition that is matched. When a temporary-definition is created, the name used for the temporary-definition is the effective-name of the glossary-button that caused the temporary-definition to be created. Some examples of this are as follows:
Glossary-button name Name of temporary-definition(1) syntax \t syntax
Before creating a new temporary-definition, Guide sees if its effective-name is the same as that of any existing temporary-definition; if a match occurs, the existing temporary-definition is used (even if its placement is different). Thus redundant creation of temporary-definitions is avoided. Moreover authors can exploit this by sharing the same temporary-definition between two buttons that the user sees under separate guises (e.g. Manager and Fire Officer alias Manager). Authors should, however, ensure that glossary-buttons that are fundamentally different have different effective-names. For instance it would be foolish if examples (3) and (4) above occurred in the same source, given that they have the same effective-name; if they did, and the user selected (3) and then (4), the replacement of (3) would be used as the replacement of (4).
If, as an author, you wish to investigate the names of temporary-definitions, try undoing the replacement of a glossary-button when in author-display. The replacement will disappear underneath the button-name that is its temporary-definition.
When a view is saved, temporary-definitions are normally omitted. There is, however, a special option on the \f3Save command (q.v.) to save temporary-definitions as well. When saved in this way, temporary-definitions are promoted to normal world-definitions. When the glossary-view is saved, the user is encouraged to use this special option, thus allowing him to build his own definitions-file. Indeed if a glossary-view was saved without this special option, the usual outcome would be that nothing was saved. This is because, unless the user has edited it, the glossary-view will consist only of temporary-definitions.
(This Section can be skipped on a first reading.)
We have already explained how regional-definitions take precedence over world-definitions; however authors may sometimes be worried about duplicate world-definitions, so we will explain Guide's searching mechanisms. When a dependent button depends on a definition, Guide needs to search for that definition. If a button does have more than one definition the one chosen obviously depends on Guide's order of search. This search proceeds in three stages: firstly temporary-definitions in the current glossary-view are examined. (If you already have a temporary-definition, you do not need a new one.) If this first search fails, a search is made for the necessary definition: this search covers the source and then, as the third and final stage, the definitions-file. The definitions-file is searched sequentially from beginning to end, and thus the earliest definition in the file takes precedence.
The above somewhat complicated explanations can be summarised in the following advice:
Given that the replacements of dependent buttons are normally temporary to the current session it is not sensible to edit them -- and thus Guide gives a warning if you try to do so. If you, as author, want to change a definition make sure you change the definition itself rather than a transient copy of it.
Some document viewing systems have a `goto' mechanism. For example the reader might ask to go to a section of the document that explains the term `inflation'. Indeed some people claim that such links are the essence of hypertext, in the same way as authors of early tracts on programming languages viewed the goto as a vital programming primitive. Guide offers a different approach: instead of going to a different place in the document, the Guide user makes a copy of the desired material by selecting a dependent button. Thus a usage-button called inflation might make a copy of the corresponding definition of `inflation' and insert this as the replacement of the button. The advantage of the copying is that the user is much less likely to get lost; a usage-button can, for example, be undone at any time, thus returning to the original button. Such re-tracing of steps tends to be more disorienting with a goto mechanism. However if, as author, you really want a goto mechanism, refer to our earlier example of the .Dl "see carburettor" action-button.
This concludes the discussion of dependent buttons. We finish the Chapter by discussing the automatic replacement of buttons.
In some applications it is useful if certain buttons are automatically selected when material is loaded, thus tailoring it to the requirements of a particular kind of user. Guide contains three mechanisms whereby buttons are replaced automatically on loading. Each mechanism meets a different user need.
The first is an extremely simple mechanism. The user can, on option, save that source with its current settings of replace-buttons. This is a way of dumping the current state of play, so that play can resume later. It is also a mechanism for authors who do not want their readers to start at the very top level.
The second and third mechanisms are systemic ones whereby buttons with specific properties can be selected automatically. The two mechanisms are called button-conditions and pre-set replacements, and are described in the next Section.
Several principles are common to these mechanisms:
A button-condition is a relation that is attached to an individual replace-button; if the relation is true the button is automatically replaced. For example the button-condition may cause the button to be expanded if the reader belongs to a given class or if some external condition holds (e.g. a `Scottish Law' option has been selected for a legal document). As a further example the author may require that certain paragraphs only be visible to the reader if a certain button-condition holds. In the case the paragraphs can be made the replacement of a replace-button that has a null name but has a button-condition attached. If the button-condition is false the reader sees nothing; if it is true he sees the extra paragraphs.
A button-condition is prefixed by a question-mark and comes before a button-name. (The question-mark must come at the very start of the button: it cannot be preceded by spaces, ghosts, contexts, etc.) The actual name of the button should therefore not begin with a question-mark, so that it is not mis-interpreted as a button-condition. An example of a button-condition is
? v == 3 || @{ENV-NAME} != "Scottish" Button-name
The button-condition is terminated by a tab (or if the button has no name and no extensions, by the end of the button). Like an extension, a button-condition is only visible when in author-display.
Button-conditions may involve strings and/or integers. As far as possible, their syntax has been designed to resemble the C language. In detail the syntax is as follows. A button-condition is a sequence of one or more relations connected by && (and) or || (or) operators. Relations are evaluated from left to right until the overall result of the button-condition is known. (Hence in the above example if v is equal to 3 then the second relation is not evaluated, since the overall result is known to be true.) Each relation takes the form
operand relational-operator operand or operand
where the possible relational-operators are: ==, !=, >, <, >= and <=. If the relational-operator and its second operand are omitted, then they are assumed to be `not equal to 0' or, for a string that does not represent an integer, `not equal to the null string'. It is an error to compare a string with an integer unless the string represents an integer, e.g. the string "-123". The null string is considered to be 0. (As a short-cut, Guide allows the symbols &&, || and == to be abbreviated as & and | and =, respectively).
The possible operands are:
A button-condition is evaluated only when the button is first painted on the screen. Scrolling the button on and off the screen will not cause its button-condition to be re-evaluated. Button-conditions are therefore not designed to cause button selections to dynamically change while a document is being read -- this would be upsetting to readers. (For example if ENV-NAME was changed to "Scottish" this would not immediately cause all the button-conditions that used it to be re-evaluated.) If, however, a replacement containing a button is undone and then re-selected, then this counts as a new painting on the screen, and the button-condition is re-evaluated. If authors really want to exploit changing button-conditions they can do it as follows: place within an enquiry two buttons: button A leads to procedures for setting parameters used in button-conditions and button B leads to material that uses button-conditions, say a legal document. If the reader is deep within the legal document and wants to change the parameters used in button-conditions, he needs to undo button B in order to get to button A. The action gives him a correct view of what is happening: to change the parameters for the legal document, he should undo the whole document and start again.
When the author creates a button-condition it is only evaluated when the file is re-loaded and the appropriate button is painted on the screen.
(It is actually legal to prefix a button with more than one button-condition, and this works as an or'ing operation. This facility occasionally has uses when Guide sources are being generated mechanically, but normally it is simpler to combine the button-conditions into one, using an explicit || operator.)
The following are some examples of button-conditions:
Button-conditions do not apply to buttons in the menu.
Button-conditions are a wide-ranging facility that an author may use to control some buttons in a way the average user may not be aware of. This facility is complemented by the `pre-set' facility, which allows the user to have more immediate control over individual replace-buttons. Pre-setting is done by pointing at a replace-button and, instead of selecting it with button A in the normal way, special-selecting it by using button C. (This facility is normally inhibited unless a special option is set -- see the Guide manual page. Otherwise it is likely to confuse beginners who simply press the wrong mouse-button.) If you perform such a pre-setting, not only is the button itself replaced, but all replace-buttons of the same name are automatically replaced too. Thus if a document contains several local-buttons called More, then pre-setting one of them will cause the lot to be replaced. Similarly if a document contains several enquiries of the form
Are you a Beginner or an Expert?
then pre-setting the Expert button will cause all such enquiries to have the expert's replacement.
Some authors bear in mind the pre-set facility when designing replace-buttons. If you want to exploit this facility, choose a systematic convention for button-names rather than arbitrary names. One possible convention, shown by the example in Figure 1, is as follows: if the sole purpose of a replace-button is to hide detail then that replace-button should have the name `More'. Given this convention, the reader who wants all this detail can simply pre-set More. (We should emphasize this is a possible convention; there is still a lot to be learned about the most effective techniques for hypertext authorship, and authors are encouraged to try their own ideas. Guide aims to provide a set of authorship aids rather than a straitjacket.)
Pre-settings are built into source files. Thus when a source is saved and subsequently re-used, any pre-settings within it will still apply. (To be exact, the list of pre-sets belongs to the first view, and is saved when this is saved.) Again this facility can be exploited by authors: if, for example, a source contains one or more occurrences of the enquiry
Are you using a PERQ or a SUN?
then the version of the source installed on PERQs could have PERQ pre-set.
Users can make a pre-setting in either of two ways. One is to wait until the desired replace-button is in view and then to special-select it in the way described above. The second is to edit the list of pre-set buttons. This list of pre-set buttons occurs at the very start of the document (provided, of course, that Guide has been set to allow pre-setting), and is enclosed within the control characters representing the start and end of the pre-set list. It is only visible in author-display. As an example, if More and PERQ are pre-set, the start of the document will appear, when in author-display, as
This list of pre-sets can be edited and thus pre-settings can be added, changed or deleted. (Such changes are not, however, retrospective: if a pre-setting is deleted, Guide cannot undo all its previous actions based on the former pre-setting; if you really want to wipe the slate clean you should save the source and start again from scratch.)
The rest of this Section gives an exact definition of the pre-setting mechanisms. It can be skipped on a first reading.
If pre-settings are changed by editing, their time of application, i.e. the time when they come into effect, is when the user next switches from author-display back to reader-display. If a pre-setting is made by special-selecting, then the newly pre-set name is added to the end of the list of pre-settings, and the time of application is immediate. The way the pre-settings are effected is identical in the two cases: the entire source is scanned and each replace-button that matches a pre-set name is marked to be replaced, at the next viewing, by its replacement.
Finally some technical points:
(This facility, a fourth way of automatically selecting buttons, has now been superseded by the use of the U button-condition-variable. However it is retained for compatibility purposes.)
Each replace-button has an asking-level, which is a digit between 0 and 3. When a button is created its asking-level is set to 1, but this can be changed using the \f3Ask-level command (see Chapter 5).
Associated with each user is a user-level which, like the asking-level, defaults to 1. However a user can change his user-level by placing in an argument list the option `-ud' where d is a digit. When a source file is loaded, all the replace-buttons for which the asking-level is less than the current user-level are automatically replaced. Thus the command
guide -u4 tutorial
causes all the replace-buttons within the source file tutorial to be replaced, since the user-level is 4 and all asking-levels must be less than or equal to three. In this case the user would see a completely expanded document, containing no replace-buttons at all.
Authors can use asking-levels for the following purposes:
Note that replacements are only made when the relevant source is loaded. Thus if you change asking-levels on some buttons, you will only see the effect when the source has been saved in a file and then re-loaded.
As we have said, any string of characters can be used for the name of a replace-button or glossary-button (provided that the button-name does not begin with a question-mark). However these names cannot themselves contain other buttons, nor can they contain enquiries.
It is possible, but unusual, to have whole sentences as names -- or even whole paragraphs. Even if a name is so long that it is partly out of the frame-of-view, Guide still allows it to be selected.
A Guide source file can be treated as an ordinary ASCII file in your file system. It can be fed to other programs, such as a spelling checker or editor.
You can use an ordinary text editor to edit Guide sources (though in earlier releases of Guide, pictures embedded within files were represented by arbitrary binary codes which can upset some editors -- current Guide releases represent pictures using printable characters so there is no problem), but you should be careful to maintain Guide structuring. Because of the danger with such edits, Guide checks the structuring of source files it loads and rejects a source if it contains errors (e.g. the start of an enquiry not matched by the corresponding end).
Guide structure is represented within the source file by lines that have a similar format to Troff requests. Full details are available in a separate document, but these are only of interest to a minority; a simple browse through a few source files will soon give a feeling for their format. Guide source files should not contain any characters with codes less than 32, apart from horizontal tabs, vertical tabs, newline characters, form-feeds or (in source files generated by early Guide releases) parts of pictures. (Some special details: a form-feed behaves like a newline in Guide, but has the added property that nothing more is output in the current frame-of-view, i.e. material beyond the form-feed starts on a new `page'. Form-feeds are made visible when in author display; they are represented by a `PTO' character -- and vertical tabs are represented by a downward arrow. Setting of positions for vertical tabs is covered in the Guide manual page.) If an illegal character is found, Guide gives an error message, and replaces the errant character with a question mark.
The Guide source can involve pictures as well as text. A picture is a rectangular bit-map of a fixed height and width. To the reader a picture is not fundamentally different from a character of the text. For example if he places the marker-bar on a picture and types the DELETE key the picture will be deleted. The marker-bar can only be placed at the end of a picture, not within one. If a picture is too wide or high for the Guide screen it is clipped.
Authors need to know something about how pictures are placed on the screen, and how they are created. A picture is treated as a character that may have a large `descender' that causes the current line to become taller than a normal text line. (The height of a tall line is rounded up so that it is an integral number of normal lines.) Tall lines behave like normal text lines: for example the active area of any button on a tall line extends the full height of the line. There is, however, one exception to this treatment: for placing the marker-bar, the line is treated as if it were a text line of the normal height, i.e. the descender region is ignored; the reason for this rule is to avoid ambiguity about where the marker-bar really is.
Pictures may be used freely within button-names, but authors should design their pictures carefully when using this facility. Firstly, although text within button-names is automatically highlighted by Guide in some way (e.g. it is emboldened or underlined), pictures within buttons look just like pictures outside buttons, except that on colour displays they take on the colour used for the button. Thus the picture itself should make the context clear, e.g. the picture may be made to look like a physical button.
Secondly, Guide does not support the concept of comparing two pictures to see if they are `equal'; indeed this is a hard concept to define in a natural way. Thus, when trying to match a dependent button with a corresponding definition, Guide ignores all pictures in button-names; for example, a button-name that consists entirely of picture(s) is treated as null in this matching process. Authors are therefore recommended to adopt the following rules:
Buttons containing pictures cannot be pre-set, because otherwise the user would be deceived into thinking that all buttons matching the given picture had been pre-set. By the same token, pictures cannot appear in the list of pre-set buttons.
When the user undoes a replacement, a pop-up menu appears. This menu contains one line for each button that the replacement lies within. A desirable characteristic of any pop-up menu is that all lines in the menu should have the same height: tall lines including large pictures would upset the balance of the menu. Hence, within these pop-up menus, Guide represents every picture by a fixed small icon.
Guide has no features for drawing pictures, scaling them or changing them in any way -- a picture is a single indivisible unit and the only permissible editing operation is to delete a complete picture. Pictures therefore need to be created outside Guide by specialist software.
A Guide source file can be any of the following:
When it loads a file, Guide decides whether the file appears to be a raw picture and, if so, treats it as such. Thus the user does not have to take any special actions to load a picture file. To insert a raw picture into the text, the author performs the following:
Files containing pictures can be saved in the ordinary way. (A source that just consists of a picture is saved as a null Guide text file with a picture in it: this is a slightly different representation from a raw picture and therefore cannot be used by the picture-drawing software.)
Pictures can occur anywhere except within the pre-set list. .up
Chapter 3 Arguments
In the early days of programming one of the biggest break-throughs was the invention of subroutines with arguments. This made programming easier, and made programs both shorter and easier to maintain. It turns out that a similar concept is equally applicable to hypertext: if, when some text is inserted, the author can insert some variable elements that depend on the current context, then flexibility is greatly increased. Guide's facilities for arguments achieve this. A Guide definition can have arguments that are plugged in when the definition is inserted.
Arguments are attached as extensions to the name of a dependent button. An example is a usage-button:
Clause 5 arg sum=1000 arg company=Good Works Ltd.
This behaves exactly like an ordinary usage-button called Clause 5,
except that Guide inserts two extra regional-definitions at the start of
the replacement.
These regional-definitions correspond to the two arguments sum and company.
The former is defined as 1000 and the latter as Good Works Ltd..
(Guide also creates a ghost to enclose these two regional-definitions, so that
the reader does not see them. It is a principle of Guide's mechanisms
for arguments that they must be invisible to the ordinary reader.)
These regional-definitions can be used, within the replacement of Clause 5, in the normal way: for example a line might read:
It will be insured for sum pounds.
Here sum is an ordinary usage-button, which uses the regional-definition of sum that was created by Guide. We call this an argument-insertion. When the sum argument-insertion is selected it is, in our example, replaced by 1000; elsewhere there might be other usage-buttons for Clause 5 which set sum to a different value.
This is fine as far as it goes, but it requires the reader to insert the argument
by selecting the sum button.
The author usually wants the argument-insertion to be done automatically, so
that in the above example the reader never sees sum but sees the value 1000.
This might be achieved by one of Guide's mechanisms for automatically selecting
buttons, as described earlier (e.g. by attaching the button-condition ?U >= 0
to sum), but since the automatic replacement of arguments is so frequent
Guide provides a special facility for it. This uses an extra button-condition-variable,
called A.
If the author wants an argument-insertion to be performed automatically, he
prefixes the button-condition ?A to it, e.g.:
?A sum
The button-condition-variable A is set to 1 by Guide if it lies within the
replacement of a dependent button (e.g. the replacement of Clause 5 in
the case of sum); if not it is 0.
(The exact rule is that Guide takes each enclosing replacement in turn
until: (a) it gets out to the replacement of a dependent button, or (b) it gets out to the replacement of a definition-button or
outside all replacements; A is set to 1 only if case (a) applies.) The
effect of this rule in our example is that the usages of Clause 5 have
the arguments automatically plugged in, but if the author (or, less likely, the
reader) looks at the definition of Clause 5, the argument-insertions are
not replaced, and thus can be seen in their original form.
As an author you are strongly encouraged to place ?A at the start of
every button that uses an argument: this has documentation value as well as
functional value.
Our example has shown a simple usage-button. Arguments can equally well be applied to more complex usage-buttons, e.g.
Example echo ... load-def ... run ... arg abc=xyz
(Here the regional-definition of abc would be inserted at the end of
the replacement, since arg is after the other constructors. Its
position, however, makes no difference to its scope: it still applies to the
replacement.)
Arguments can also be attached to glossary-buttons. Here the obvious rule for authors is that if two glossary-buttons use the same definition but with different arguments, then they should be given different effective-names. (If you doubt the wisdom of this, consider the following two glossary-buttons:
Clause 5
arg sum=20
arg sum=15,000
If the first is selected, the definition of Clause 5, with the argument 20, goes into the glossary-view; if the second is then selected, since it has the same name, it will use the existing definition, even though its argument is different.)
Note that an arg attached to a button just means `create a regional-definition
at the start of its replacement', and there are no special rules about it.
In particular:
company argument).
See below for a discussion of how default values can be inserted.
Note that in name-value pairs such as sum=1000 spaces round the equals
sign are significant.
Therefore there should be no spaces there unless the author actually wants spaces
at the end of the argument name and/or the start of its value.
It is valuable to use arguments as the equivalent of Boolean variables in programming: for example, an extra sentence might be included in Clause 5 if it had the argument:
arg law=Scottish
To achieve this, the extra sentence should be made the replacement of a local-button with a null name but with the button-condition:
?A && @d[law] && @[law] == "Scottish"
If the argument law exists and has the value Scottish the button is
selected and the extra sentence
is displayed; otherwise the button is not selected and the reader sees nothing, since the button has a null name.
A generalization of this is where the author wants an if-then-else or a `case' facility, e.g.:
Scottish, and Text B otherwise.
Scottish, Text B if it is EEC,
Text C if it is USA, etc.
This can be done with Guide enquiries. For example (a) above can be achieved by placing within an enquiry the two local-buttons:
?A && @d[law] && @[law] == "Scottish"and?A
The replacement of the first button is Text A, and the second Text B.
By Guide's normal rules for automatic replacements, the first button within the
enquiry that has a true button-condition is selected.
Thus the second button is selected only if the first does not apply.
(The reason why ?A rather than ?1 is used on the second button
above is to ensure that, when the definition of Clause 5 is viewed, neither
button is selected, and the enquiry itself can be seen; this will make it easier
for the author to see what is going on.)
A similar mechanism to the above use of an enquiry can be used to provide a default value for an argument, e.g. assume that sum is to be taken to be 500 when no argument sum is present. This can be achieved by an enquiry containing the two buttons:
?A && @d[sum]sum and?A
The first of these buttons is a usage-button that inserts the value of sum if it exists, and the second is a local-button whose replacement is 500.
(As a further stage, which might be valuable if the value of sum were used a lot of times within the replacement of Clause 5, the above enquiry could be made the replacement of a regional-definition, called, say, actual-sum, placed at the start of the replacement of Clause 5. The usage-button:
?A actual-sum
would then insert the value of sum if it were defined, and the value 500 otherwise.)
Fearless Guide authors can even use techniques like the above to deal
with variable-length lists of arguments, e.g. a sequence of arguments name1,
name2, name3, etc., representing names of people.
Iteration through the list can be achieved by recursive Guide definition-buttons.
An alternative way of achieving default values for arguments is by the use of definitions. There could, for example, be a regional-definition (or a world-definition) of sum, with 500 as its replacement. This definition should be placed so that its scope covers all usage-buttons and glossary-buttons that use Clause 5. Then if sum does occur as an argument to a button a new regional-definition of sum will be created at the start of the button's replacement. This will, within the button's replacement, override the original (outer) definition (since when two definitions apply the inner one takes precedence). If sum does not occur as an argument the original definition will apply. .up
Chapter 4 Layers and contexts
This Chapter describes two related concepts: layers and contexts.
Instead of storing a Guide source in a single file, it can be saved in a set of related files, each representing a different layer. The simplest use of layers is to have two layers: the top layer containing Guide's hypertext `mark-up', and the bottom layer containing the underlying text. The Guide user can load the top-layer file, and this will automatically load the lower layer(s) too -- indeed in many cases users do not need to be aware that input is multi-layer. The bottom layer might, however, be valuable for feeding to other software: it could, for example, be a program that was to be fed to a compiler. Indeed, compilation might be initiated by a Compile button in the Guide source; this button could do a multi-layer Save, and then feed the bottom layer to the compiler.
Layers have many uses, some of them in conjunction with applying Guide mark-up to read-only material at the bottom layer. Many of these uses, however, depend on contexts that designate certain material to be annotations at higher layers. We will therefore describe contexts now, and return to the topic of layers at the end of the Chapter.
Contexts allow material to be displayed in different fonts, colours, etc. The facility is based on the logical nature of material, rather than just on its physical appearance. This is so that:
These advantages have to be paid for by a bit of extra forethought by authors, but the price is generally worth it.
It is best to explain contexts by means of an example. Assume a Guide document covers tax law and is a mixture of quotations from the law and commentary. The author wishes to distinguish the quotations from the commentary by displaying the former in a different font. To do this, the author defines a context which he calls Quotation. Contexts are defined in a context-table, which is a sequence of entries, each being a context-spec that defines the name of a context and some attributes such as fonts and colours. (Normally, if a source file has its own special contexts, a context-table is placed at the start of the file, when it is saved by Guide.) Therefore in our example the author prepares a context-table containing a context-spec for Quotation. The author of the document encloses each quotation within a Quotation context, thus causing it to appear in the font prescribed by the current context-spec for Quotation. .KF
Figure 6: use of contexts
Figure 6 shows how contexts look in author-display; in this case there are three contexts: Quotation, Title and Section-heading. You can see their names as extra entries at the bottom of the menu. Each of the three contexts has a different font associated with it, and there is one occurrence of Quotation and Title in view, plus two occurrences of Section-heading. For the author's benefit, there is a reverse-video control character at the beginning and end of each occurrence of a context. The initial `control character' is actually a sequence of characters, consisting of the character `{' followed by the name of the context -- displayed in the context's font. The closing control character is a reverse-video `}'. These reverse-video characters are not, of course, visible to readers: readers just see the different fonts.
In order to lessen the need for authors to create completely new
contexts, Guide has a context-library of potentially useful
contexts. Sites may augment the context-library that is issued
with Guide by adding further contexts to cover their own common needs.
The file contexts.guide, in the library of Guide source files,
contains the context-library; the body of this file gives a brief example of each context defined in the
context-library.
Authors can also augment the context-library by creating a contexts.guide file
within the current directory; the augment applies to all Guide sources within that directory.
When Guide has finished loading a file or other material it searches in the context-library for any undefined contexts.
When it is running, Guide maintains a single current-context-table, which covers all the documents currently loaded. As each new Guide source file is loaded, its context-table is added to this overall table. When a source file is saved in source form, Guide creates, at the front of the saved file, a context-table. This covers all the contexts that the source file uses (but which are not in the context-library, or which have different attributes from the ones in the library -- e.g. the authors may have their own taste in colours). Hopefully this mechanism is such a `natural' one that authors and readers do not need to be aware of it. In our example, context-specs for Quotation, Title and Section-heading -- assuming they are not in the context-library -- will be placed in the context-table on the front of the tax file when it is saved.
When Guide saves an occurrence of a context, the start of this occurrence is marked with its name. Consider Quotation in our example; when the example file is loaded, Guide searches its current-context-table for a context-spec for Quotation. (It is an error if there is no such context-spec, and there is no context-spec in the context-library either.) The attributes of the context-spec are then used for displaying the context. Often this context-spec will have come from the context-table that was prepared by the original author and loaded at the start of the current file. However the user can override this table with his own, different table, that may, for example:
Such flexibility is the reason why Guide identifies contexts by logical names such as Quotation and does not have attributes Another reason is to make maintenance easier: it may be desired, for example, to identify all the quotations in the tax file and place an icon on the front of each; this is easy to do either within Guide itself, or, if there are a huge number of quotations, perhaps by a specially written script to perform a systemic edit on the tax file and any other Guide files that need changing.. directly attached to the text.
We discuss, in a subsequent Section, the exact rules covering overriding, and the rules for using the same context in different views.
New contexts can be created using the Alter-context-table menu-command. Occurrences of existing contexts are created in just the same way as other Guide constructs such as enquiries and ghosts are created. When in author-display Guide augments its normal menu by adding on extra entry for every context-spec in its current-context-table. Thus in Figure 6 the current-context-table contained the three contexts shown in the menu: the Quotation context, for example, causes +Quotation to appear in the menu. When the author wishes to create a quotation he selects +Quotation. Just as with other new constructions, a null context then appears. The null context looks like this (but in reverse-video):
{Quotation}
The author types the content of the context between these two control characters. The ordinary Guide rule that constructions should be properly nested within one another applies to contexts too: it is impossible to create contexts that are not properly nested.
A good way for authors to get an initial feel for contexts without the need to create any new ones is to load a trial document in one view and the library file contexts.guide in another. Since the latter contains context-library, the names of all contexts in the library will appear in the Guide menu. Thus occurrences of these contexts can be created in the trial document.
One extra facility worth mentioning is that context-specs can also be specified for: (a) all enquiries, (b) all ghosts or (c) all main text within the scope of the context-spec. In particular it may be useful to make enquiries stand out in some way. Specifying a context-spec for `main text' is equivalent to enclosing all the text within a context with the specified attributes, e.g. it could be used to specify the default font for a view, or, if the context-spec is loaded within the menu, for the whole Guide screen.
Two kinds of attributes can be attached to a context-spec: appearance attributes and control attributes. Appearance attributes are concerned with font and colour.
Fonts and colours can be specified for the normal text within a context and/or for the replace-buttons within the context. Colours are specified as a set of RGB values for the foreground colour and, if desired, for the background as well. Unlike fonts, foreground and background colours apply to monochrome pictures as well as text. On a monochrome display settings of the colour attributes are ignored.
If an appearance attribute is not set for a context then, for each occurrence of that context, the attribute is inherited from the context containing it. (Under the X windows implementation of Guide, individual fields of the X Logical Font Description can be inherited. Thus a font can be `like the containing font, but Courier'; furthermore it is possible to specify increments for numeric fields, e.g. `like the containing font, but two points bigger'.) If the context is not enclosed within anything, the built-in default values (i.e. Guide's default use of font, foreground colour, background colour) are used. The attributes for a context cover all replacements, etc., with it. Thus for example if our Quotations are displayed green-on-blue, then any replacements within that context are displayed as green-on-blue -- even if the replacement comes from a usage-button that loads from a different file. The colour within the context will only change from green-on-blue if it contains a further, nested, context that has a different colour attribute.
By using appearance attributes on the context-spec for `main text' it is possible to override all Guide's default fonts and colours. For some information on this, try loading the library file standard_menu and viewing it in author-display.
In addition to the appearance attributes, three possible kinds of control attribute can be set. Firstly the saving-strings are a pair of strings S1 and S2. When material is saved in text form -- this is not the standard saving option -- or copied to the cut-buffer, the string S1 is output at the start of each occurrence of the context and the string S2 at the end. (S1 and S2 could be strings that cause a font change if the output is subsequently fed to, say, troff; in this case S1 might be `\fI' and S2 might be `\fP'.) The second type of control attribute is the display attribute, which caters for further options on how the context is displayed. The third type of attribute allows for a program-command-sequence to be attached to a context; every time a menu-command (e.g. +Quotation) is used to create an instance of a context, this sequence is executed (see example in the library file contexts.guide).
Contexts (and ghosts -- see below) can be used within buttons. In particular, contexts can be used to change the font and/or colour of all or part of individual buttons. Contexts can also be used within button-conditions and extensions; although such material is displayed by Guide in a fixed font, which is not affected by contexts, contexts can be used to change the colour. It is, for example, possible to display in green selected shell scripts that are embedded within buttons.
Ghosts are valuable for placing commentary within buttons. They are otherwise completely ignored. To reinforce the property that a ghost is not part of a button, but is a commentary about it, ghosts within buttons are displayed in the normal font used for ghosts rather than in the fonts used for buttons. A context that has its display attribute set to make it appear like a ghost counts as a ghost rather than a true context, and is thus ignored within buttons too.
This Section contains technical detail that may only be of interest to authors with more advanced applications.
Multiple views: The Guide screen can be divided into several separate views. For example our tax document containing the Quotation context may be in one view and another document, containing other contexts, may be in a second view. This second document may even contain a context called Quotation. If the second document has a context-spec for Quotation (which may well have different attributes from the one used in the first document) then this second context-spec is used. Otherwise the first context-spec is used. It is quite legal for there to be two context-specs for the same context, provided their scopes do not overlap.
Dependent buttons: With a dependent button the replacement is a copy of some material from elsewhere; it is often a copy of a definition that occurs either within the current source or within a separate file; alternatively it might be a copy of a file. As we have said in a previous chapter, Guide gives a warning if an attempt is made to edit such `transient' material since the editing would apply to a copy rather than to the original. To summarise the rest of this paragraph: context-specs within transient material are best left alone and are therefore made invisible to authors, though they do affect fonts, etc., within the transient material. The details are as follows. If transient material includes a context-table (as it would if our tax file were loaded as transient material) then Guide, in the normal way, incorporates the context-table into its current-context-table. However the scope of these transient context-specs is just that particular piece of transient material (e.g. a replacement of a usage-button or glossary-button) -- not the whole view. Thus context-specs within transient material do not affect the material within which the transient material is embedded. They only apply to contexts that lie wholly within a particular piece of transient material. The names of such transient context-specs do not appear in the Guide menu.
Clashing context-specs: We have seen that, within the current-context-table, there may be several entries corresponding to the same name, and that these may have different attributes. When this happens, Guide has the following rules -- hopefully all representing the common-sense effects that users would expect -- for resolving the conflict. When an occurrence of a context is loaded or newly created, its name is compared with names of contexts in the current-context-table in the following way:
Overriding: If a new context-spec is loaded and this lies within the scope of a current context-spec of the same name, then the new context-spec is ignored (though Guide has a switch to give an optional warning in this case). Thus if a user loads his own context-table in view 1 and this contains a context-spec for Quotation, then this will override any other context-spec for Quotation that is subsequently loaded within view 1 -- i.e. the user has overridden the attributes embedded in the document.
Copying: If a context is copied then the same rules apply as for loading. If, however, no context-spec fits the destination of the copy (e.g. copying out of transient material), then the context-spec that applied to the source of the copy is re-loaded in the destination. (Two examples: (a) if a transient quotation were copied into view 3, for which the Quotation context had not been defined, then a new context-spec for Quotation for view 3 would be created for that view; (b) if there are different context-specs for Quotations in view 1 and view 2, then when a quotation is copied into view 1 or view 2 it takes on the attributes of the destination view.) Moving follows the same rules as copying.
Lasting context-specs: If the total content of a view is removed or replaced (e.g. using Replace-all under the New command) then the slate is wiped clean and all context-specs that belong only to that view are deleted. However if the user wants to have a context-table that will apply throughout a Guide session, he can load that context-table within the menu. (Any Guide source file can be used as the Guide menu: in particular the menu can be a source file that supports the standard menu-buttons but also has a context-table. See the Guide manual page for details.) Context-specs loaded as the menu apply to all views, and are only removed if the menu is over-ridden.
Slanted fonts: Some fonts are slanted in such a way that the rectangle of one character can overlap its neighbour. Occasionally, e.g. when inserting an edit between two overlapping characters, this can cause bits of characters on the display to get lost.
Saving: When Guide saves a source file it places a context-table on the front. As we have said, this includes all context-specs for contexts either used or defined (other than transiently) in the saved material. Occasionally Guide may be over-zealous and include a context-spec which, although once used, has had all references to it deleted.
Context names: Names of contexts must be a sequence of one or more of the following characters: a lower-case letter, an upper-case letter, a digit, or the punctuation characters "+\(**-/_|=.?". Matching of names between a context and a context-spec must be absolute, e.g. `Quotation' does not match `quotation'.
Distance between lines: The distance between lines is constant for each view and allows for the tallest font currently loaded in that view. Thus if one context-spec in view 2 uses, say, a 36-point font, then all the lines in view 2 will be rather far apart (even if the huge font is not actually used).
Definitions loaded from a file: Assume that a glossary-button (or a usage-button) uses the definition of Bulgaria and that, within that definition, there is an occurrence of a context called Cyrillic. When Guide loads this context it searches, in the normal way, to see if it is in the current-context-table. If not it sees if Cyrillic is defined in the context-table of the file from which the definition of Bulgaria was loaded, and finally searches in the normal way in the context-library. Again, these rules are hopefully natural ones.
In addition to the attributes mentioned so far, a context can be made to be an annotation. This is done by giving it annotation-properties, which assign the context, and everything within it, to a certain layer in a multi-layer save, if the Save command is so configured. (When we say `everything within them', there is a possible ambiguity: for example a layer 1 annotation could lie within a layer 2 annotation. The ambiguity is resolved in the natural way, i.e. in our example everything within the layer 2 annotation would belong to layer 2 except the material within the layer 1 annotation.) The Save command is configured by an option in its menu which allows a choice from several recipes for defining the layers. At one extreme, the recipe can specify that there is only one layer, in which case an annotation is like a normal context. At the other extreme there could be several separate annotation layers, with a layer beneath that for the remaining mark-up, with a text layer at the very bottom.
Annotations are useful for adding comments to an existing file without interfering with that file. They are also useful for giving various versions of a hyperdocument. In particular, if a hyperdocument is saved as, say, 3 layers of files, it is possible to load any of these 3 files into Guide -- each layer automatically bringing in the lower layers. Thus loading the second layer would cut out the material at the top layer, which might relate to a special version of the hyperdocument.
If a file is saved in several layers, the lower layers should not be edited separately. Instead the top layer should be loaded into Guide, the edits done (which might relate to lower layers), and the hyperdocument saved again.
Finally, we have been rather vague about the mark-up layer, and should define it more precisely. If there is a separate mark-up layer this consists of: all hypertext mark-up, ghosts and everything within them, annotations and everything within them (unless already saved at a higher layer), pictures, names of all buttons except glossary-buttons, extensions to glossary-buttons. Contexts that are invisible to readers are treated as ghosts. .up
Chapter 5 The menu
This Chapter lists all the commands that may be displayed on the menu. The commands concerned with structural editing are only available in author-display. Most of the commands act immediately they are selected, but a few involve a preliminary dialogue with the user. In some cases Guide may ask you to type a line, for example a filename or an argument list; Guide does not act on the line until you have typed the newline character, thus allowing typing errors to be corrected.
There are two types of material that you might want to save in a file during a Guide session:
The \f3Save command covers all kinds of saving. It asks you questions about what and where to save. The normal case is assumed to be saving a source file without its settings of buttons; other cases are covered by a `Special options' sub-menu.
If you have several views then if you save the text you get the lot. If you save the source, on the other hand, you may want to put the views in separate source files (e.g. to treat a glossary-view separately). Guide therefore saves sources of views one at a time, asking what to do in each case.
If you save a source file that contains no Guide structure, and which, when loaded, contained no Guide requests, then the file is saved as straight text. You can therefore use such a file as a normal text file, e.g. you could feed it to a compiler. As a result you can even use Guide to edit text files -- though an ordinary editor would probably be easier to use for this purpose.
The \f3Author command switches to author-display, and the \f3Reader\fP command switches back to the normal reader-display.
The \f3Block-edit command is used for moving, copying or deleting blocks of text and/or pictures. It is described in Chapter 2.
The \f3Find command is often best used in author-display. This is because, although basically simple, the command has properties that may confuse the naive user. The command searches for a string of characters, defined by the user. There are two types of search:
Searches may begin either at the start of the source or at the marker-bar, according to the user's choice. In all cases the search is thorough in the sense that it covers all views, and explores material that is hidden (e.g. an unexpanded replacement or the text of an expanded enquiry). The search does not, however, cover the replacement of dependent buttons that have not been selected, since the replacement for these will not have been loaded. (Moreover the search does not in itself cause any buttons to be automatically selected.) If the search is initiated by a user in reader-display, material that the reader would never see (ghosts, button-conditions, extensions to buttons) is omitted from the search. Matching is on a character by character basis and is not case-sensitive -- thus `Pig' matches `PIG' or `pig'. If the match succeeds, the marker-bar is placed at the end of the string that has been found, and the appropriate frame-of-view is re-focussed so that the marker-bar is in view. Guide tries to be intelligent about this re-focussing, so that the frame-of-view starts at an appropriate place, such as the start of a replacement.
If the string is found in hidden material, Guide automatically does the necessary expansions and/or undoings to reveal the string. (An example when both undoing and expanding are necessary is when one branch of an enquiry has been expanded, but the string is found in a different branch.) The search ignores any pictures or transcripts embedded in the source. Structural delimiters generally affect the matching process: for example `XY' will not match X followed by the start of a replacement followed by Y. Contexts that are visible to readers are, however, a natural exception to this: thus `XY' will match X followed by the start of the (e.g.) Emphasized context followed by Y.
When the user types the string to be found, a newline character acts as the terminator. If the user wants to put a newline in the search string, a vertical tab character should be typed. When asking the user to type a string, Guide translates vertical tabs into newlines.
Guide can be made to perform an automatic \f3Find on loading by using the -f option, e.g.
Normally the Find is `animated' in the sense that the user is shown all the scrolling, button selections, etc., needed to reach the quarry. This animation can, however, be inhibited by using the environment variable GUIDEFASTFIND.
guide -fcopy KKK
loads the file KKK and then finds the string `copy' within it. (The string following -f can involve Guide control characters -- unlike the string supplied by the user on a \f3Find command. This is, however, only a facility for the brave.) The automatic find on loading is particularly valuable when Guide is used as a help system. A more general facility, which covers `Within' searches and a lot more, is provided by the -do option; the Guide manual page has full details of this.
The \f3Next command continues the previous Find. The search starts where the marker-bar is currently placed.
The \f3Quit command can be used to end a Guide session, or, if there is more than one view, to delete the last view. Since quitting destroys the source, Guide gives you a warning if the source has been edited but not subsequently Saved.
The \f3New command allows you to add new source file(s) to the source. The new material can be inserted in three alternative ways:
The new material is defined by a line identical to the argument list to Guide. It can therefore contain options, e.g.:
products -v suppliers
loads products, switches on the `verify' option, and then loads and verifies suppliers. Quotes within these argument lists are ignored, but can be used to prevent spaces being taken as argument delimiters, e.g.
products -do \'Find "rear axle"\'
There is a fourth alternative, in addition to the three above: this is that the newly created view should go on top of the current view(s), thus completely obscuring them. Such views are said to be covered. To the user, covering appears like a new start, except that there is the opportunity to uncover, thus quitting from the new material and going back to the previous material. The covering mechanism could be used, for example, to implement a help system, especially when screen space is tight and it is not feasible to create a new view or a new window for the help information.
Covering/uncovering is not done through the menu, but by program-commands -- see Appendix B. Such program-commands might be invoked by a menu-button called, say, Help. When there is covered material, however, an `uncover' option appears in the pop-up undoing menu.
The \f3Down command advances your frame-of-view so that your new frame-of-view starts just beyond where the previous one left off. If you try to advance your frame-of-view beyond the end of the document, Guide will just give a view of the last line. The \f3Up command does the reverse of the \f3Down\fP command. If there are several views, the \f3Down and \f3Up\fP commands apply to the one most recently used.
The \f3+Enquiry command causes a new enquiry to be created at the position indicated by the marker-bar. Initially the new enquiry is null, but the marker-bar is re-positioned to be within the enquiry, so that you can type the characters that form the enquiry.
The \f3+Ghost command is used in a similar way, but creates a new ghost rather than a new enquiry. In addition there may be commands for creating new contexts, as described in Chapter 4.
The \f3+Glossary, \f3+Local\fP, \f3+Regional\fP, \f3+World\fP, \f3+Usage\fP and \f3+Action\fP commands are likewise similar to the \f3+Enquiry command, and are used to create the various types of button. Initially both the name of the button and, if the button is not a dependent one, its replacement are null. Thus the first task is to fill these in. As an example the following sequence of actions creates a local-button called Example, which has the replacement `pig'.
The following is a second example: it shows how to use the \f3+Enquiry and \f3+Local\fP commands to create the enquiry:
Is it RED or GREEN?
.Gc "" E 16 "Is it" .Gc "" B 4 "RED" \h'-.7m' .Gc "" b 1 "" \h'-.7m' .Gc "" e 17
The marker-bar will be after the `D'.
.Gc " 5) Place the marker-bar after the " b 1 at the end of the RED replace-button.
.Gc " 9) Place the marker-bar after the " b 1 at the end of the GREEN replace-button.
You now need to supply the replacements for the two replace-buttons you have created. To do this:
The \f3Destruct command is the opposite of the \f3+Enquiry\fP, \f3+Glossary\fP, \f3+Local, \f3+Regional\fP, \f3+World\fP and \f3+Usage\fP commands. Specifically it deletes the structure in which the marker-bar is most closely embedded. No text (or picture) is deleted -- just the structuring. Thus if you delete a replace-button (with the marker-bar placed either in the button itself or in its replacement) then both the name of the button and its replacement will appear as ordinary text. (A usage-button is an exception to this: if you Destruct it, its replacement, being temporary, disappears.)
The \f3Extend command can be used to extend an existing structure. To do this you should:
As an example, if you want to turn an existing word `compiler' into a glossary-button, you could achieve this in the following way:
The stage is now set for the extension, which proceeds as follows:
There are a few rules about making extensions:
The \f3Change-button can be used to change the name, type or asking-level of a button. It works differently from other commands in that you select \f3Change-button and then place the marker-bar within the name of the button you want to change. The reason for this is that you cannot normally place the marker-bar within a button-name (because when you select a button it is replaced); the \f3Change-button command `freezes' all buttons on the screen, so that you can indeed place the marker-bar within them. Having done this, you can, if you wish, edit button-names.
The \f3Change-button command also provides mechanisms to change the asking-level of a replace-button, and, within certain limits, to change the type (e.g. to change a local-button into a regional-definition-button).
Guide has benefited from ideas and from code supplied by several people -- outstandingly by my colleagues at the University of Kent and by the staff of Office Workstations Ltd.
Appendix A Some extra detail
This Appendix describes certain details of Guide that are not likely to concern the average reader. The details are given, however, so that this manual describes exactly what Guide does.
Assume that you select a replace-button called X, and then select some other replace-buttons that occur within the replacement of X. You then undo the selection of X. Some time later you decide that you want to see the replacement of X again, so you select it. What you now see as the replacement of X is exactly what you saw when you issued the undo, i.e. the replacements you made within the replacement of X remain valid. This behaviour, which hopefully appears to be natural, is valuable when Guide contains an enquiry whose replacement involves a number of nested enquiries. The user can explore the effect of changing the response to the original enquiry, confident that he can always return to the current state without having to deal with all the nested enquiries again.
As has been said, Guide tries to lay out text so that a `word' is not broken over a line break. A word is defined as any sequence of characters ending with a space, tab (horizontal or vertical), form-feed, newline or control character. If a word is terminated by a space then that space is notionally part of the word: thus if such a word occurs at the end of a line then the last character on that line will be a space. At first sight this extra space might seem wasteful, but it needs to be present in order to allow editing (e.g. deletion of the space, as in our earlier `cross roads' example).
Similar rules about not breaking words across lines are used when material is Saved as text. Thus the layout of the Saved file mirrors the layout that would be seen on a Guide screen of the same width (assuming a fixed-width font were used).
We have discussed the use of tabs for paragraph indentation. There are two exceptions to the general rule: firstly, if a tab goes very near to the right margin (to be precise, so near that there would not be room for another tab), then subsequent overflow lines resulting from the current line are not indented. If they were, the result might be a body of text displayed in an area three characters wide -- which would be unreadable. The second exception is that a tab within a button-name does not cause subsequent lines to be indented (since the purpose of the tab is to herald the extension of the button-name, as explained in Chapter 2).
When a tab causes a sequence of lines to be indented, then it appears as if all the lines have a tab on the front. However the user can only edit the real tab, which occurs on the first line; it is impossible to put the marker-bar on the subsequent `imaginary' tabs.
Some Guide implementations allow for the writing and subsequent replaying of transcript files. A transcript records all the inputs to Guide (e.g. selection of commands or buttons, placing the marker-bar, typing of characters). Options within the Guide argument list are used to cause the writing and playing back of transcript files (see local documentation for details). When you play back a transcript, you should use the same source file(s), and have a Guide screen at least as big as the one used when the transcript was written. As a transcript plays back, the behaviour of Guide should be identical to that when the transcript was written. The only difference is that you sit back and watch, as all the action comes from the transcript. Transcripts are created as the replacement of a button (whose name, by default, is `replay'); selecting that button replays the transcript. Further details about transcripts are given in the document: Dynamic replacements.
Transcripts are not widely used, but have value in demonstrations, and in re-creating suspected bugs or unusual behaviour.
In programming language terms, Guide enquiries have static scope. (Thus if, as a result of selecting a button, an enquiry is replaced by a further button, then this second button is not considered to lie within the original enquiry.)
The main improvements of releases 4.0 onwards of Guide, as compared with previous releases, are:
From release 5 onwards:
\*(HT\fR \$3\t
.if \w'\*(HT \$3'u>(\n(I\n(IRu+1n) .br\}
..
Appendix B Commands allowed with the `Do' extension
The purpose of the
do
extension, which occurs on Guide buttons, is to add a degree
of programmability to Guide.
The
do
extension is followed by a program-command-sequence; program-commands in this sequence are
separated by semicolons or newlines.
Many of the available program-commands correspond to commands in the Guide menu, and, if so,
the program-command usually has the same name as the equivalent menu command (e.g. the
+Enquiry
program-command).
Some program-commands have composite names, for example
Find&Start.
The
Find&Start
program-command corresponds to selecting the Find menu command,
and then selecting its Start option.
It is immaterial whether the names of program-commands are written using upper-case
or lower-case letters (except that names of contexts, which can appear within names of program-commands, are case-sensitive).
An example of an extension is
do Find&Start "here"; +Glossary; Type "syntax"
This finds the string
here
(thus placing the marker-bar immediately after
the first occurrence of this string), and creates a new glossary-button.
In the same way as the +Glossary menu command, the
+Glossary
program-command creates a null glossary-button and puts the marker-bar within it.
The
Type
program-command simulates the effect of
the user typing a string at the keyboard -- in this case
syntax
is the string.
Thus the overall effect is to create a new glossary-button called
syntax.
Guide does NOT provide an elaborate programming language for writing program-commands -- there is no 600 page book to read. Instead it provides commands to effect a subset of the Guide functions. If you need variables, conditionals, looping statements and so on, you can embed Guide's program-commands within an existing programming language. The most appropriate language for this is the UNIX shell, as explained below.
Before executing a program-command-sequence, Guide copies it to a buffer. This means that even if, for example, a program-command deletes everything, execution of the program-command-sequence can continue unhindered.
The above example shows that some commands have a string as argument. This string can be a literal string, as in the above example, or it can be a string set interactively by the user. The latter can be achieved in either of two ways as illustrated by the commands below:
Type /Now type the name of the new glossary-button:/
Type ^/Is the glossary-button to be called ^syntax^ or ^format^?/
The first places the given message in the area used for the Guide menu, and waits
for the user to type a string (in exactly the same way as the user types a string
for some of the commands in the Guide menu, e.g. the filename on the Save
command).
The string typed by the user is then the effective argument to the
Type
command.
The second example, where the argument begins with the
^
character, causes the Guide menu to be used directly.
Within the argument, names enclosed within
^
characters, such as
syntax
and
format
in the above example, appear as buttons in the menu.
As is standard for all Guide sub-menus and requests to type,
the button Cancel-this is automatically put on the start of the string.
The menu therefore appears as:
(Cancel-this) Is the glossary-button to be called syntax or format?
The button selected by the user then becomes the effective value of the argument. Thus, for example, if the user had selected the syntax button, then it would be as if the command had been
Type "syntax"
If, on the other hand, the user had selected Cancel-this, then the command would have been aborted (as would any further commands and extensions associated with the currently-selected button).
An argument string can therefore follow any of the following forms:
.Xp "\fRARGSTRING" 20n
-- the quotes can, in fact, be omitted if ARGSTRING does not contain any newlines, semicolons, leading/trailing spaces, etc.,
but it is normally best to put them there.
If desired, colons can be used instead of quotes.
(It may be attractive to omit the quotes -- or use colons instead -- when the string is within a
program-command embedded in a shell-script; here a plethora of quotes can
confuse.)
.Xp /\fRARGSTRING/
.Xp ^/\fRARGSTRING/
where ARGSTRING contains at least one `button' -- a substring enclosed within
^
characters.
Within ARGSTRING the following character-pairs have special meaning: .Xp \n means a newline. (It is also permissible to have genuine newlines within ARGSTRING.) .Xp \t means a tab. (It is NOT permissible to have genuine tabs within ARGSTRING.) .Xp \f means a form-feed. .Xp \/ means a division sign. .Xp \; means a semicolon -- this may be useful for putting a semicolon within a string argument that is not enclosed in quotes. .Xp \\ means a backslash. .Xp \" means a double-quote. .Xp \: means a colon. .Xp \& is ignored. .Xp \b causes a beep, but is otherwise ignored. (This may be useful in an error message.)
The possible forms of a string argument can be concatenated, e.g.:
Find&Start "Entry for ("/Type what you want:/")"
If the user typed
VAT
in reply in the request to type, the argument would then be effectively:
Entry for (VAT)
Certain program-commands change what appears on the screen; the most obvious of
these are the
Find
commands, which re-focus the frame-of-view, set the marker-bar and may even
select or undo buttons.
Sometimes such effects are not wanted; if so, program-commands may be
executed in a `shy' way.
In this case:
Find
program-commands do not re-focus the frame-of-view, nor do they select or undo
buttons (i.e. the quarry may remain off-screen and/or hidden under a button).
Shy edits only become apparent when the user actually looks at the affected material. An example of the need for shy editing would be a program that ran in the background and periodically updated some field within the current Guide document. This field might be outside the user's current frame-of-view.
Errors and exceptions can occur as follows:
Find&Start
command fails
to find its quarry, or a
+Glossary
command is used when no
marker-bar exists. In such cases Guide either gives an explicit error message, or,
for less serious cases, simply beeps.
In all these cases the command is abandoned, and any commands that come after it, within the current program-command-sequence, are ignored.
The list of available program-commands is given below. Some commands use the marker-bar, and for these the marker-bar must be placed (e.g. by a Finding command) before the command is executed. If the command has an argument, the argument must be preceded by one or more spaces.
+Local\fR, +Regional, +World, +Usage, +Glossary, +Action, +Enquiry and +Ghost
program-commands are exactly equivalent to the corresponding commands in
the Guide menu.
In addition program-commands can be used for any contexts that appear in the menu,
e.g. if
+Abstract
appears as a context in the menu, then there is a corresponding
+Abstract
program-command.
The command
+Context-library(context-name)
(for example
+Context-library(Bigger)
) is a better way of creating an occurrence of a context that is defined in
the context-library (or one of the context-libraries, if there is a local one to augment the built-in one); it has the advantage that if the context is not already in
the menu its definition is loaded from the context-library.
.Xp Advance
advances the marker-bar beyond the end of a construction (i.e. a button,
enquiry, replacement or ghost); the marker-bar must currently
be at the end of a construction.
(To understand this command better, imagine Guide to be in author-display and
that the marker-bar is immediately before a control character that denotes the
end of a construction; the result of an
Advance
would be to place the marker-bar immediately after this control character.)
.Xp Author
is identical to the Author command in the Guide menu.
.Xp Back-to-nearest-start 28n
puts the marker-bar back to the start of the construction in which it is currently
embedded, or, if the marker-bar is not within anything, to the very start of the current document.
.Xp Bump 28n S
where S is the name of an environment variable, increases the value of S by 1; if S does not currently
exist, S is set to 1.
It is an error if S exists and does not have a numeric value.
.Xp Comment 28n S
is ignored.
It provides a facility for authors to add comments explaining the purpose of
their program-commands.
.Xp Delete-last-view
deletes the last view (this program-command used to be called
Quit&Delete-last-view
).
There must be at least two views in existence when the command is executed.
.Xp Delete-this-view
deletes the current view.
The current view is the view from which the program-command-sequence was initiated (or the
first view if initiated from the menu), unless a previous program-command in the
current sequence has changed the current view. (This program-command used to be called
Quit&Delete-this-view
).
.Xp Delete-to 28n S
finds the string S (starting from the marker-bar, and using the normal Find
mechanism), and then deletes all the characters from the character beyond the original position of the
marker-bar up to and including the last character of S.
The material to be deleted must totally textual -- it cannot include any
Guide constructions.
The
Delete-to
command is particularly useful to external programs that want to update fields
within a Guide document (e.g. when the temperature changes, the external program
finds the previous temperature field, deletes it and replaces it with the new
value -- this would, incidentally, normally be done in a shy way.)
.Xp Find 28n S
.Xp Find&Marker-bar 28n S
.Xp Find&Start 28n S
are identical to selecting Find, then selecting Marker-bar or Start,
and then typing
the string S.
Find
on its own is equivalent to
Find&Start
.
Note that finding a null string places the marker-bar at the very start, or, if finding
from the marker-bar, advances the marker-bar to the next character (or picture).
The following notes apply to all program-commands that perform a find.
The operation of finding can cause the selection and undoing of
buttons, unless the
Shyly
command has previously occurred.
The program-commands for finding normally work in the same way irrespective of whether
the user is in author-display or reader-display: they always behave like an
author-display search, i.e. they search everything.
See, however, the
Options
program-command.
Finally, the program-commands for finding always skip the button that initiated the find -- otherwise
a program-command such as
Find "xyz"
would be likely to find the occurrence of xyz within the command itself.
.Xp Find&Start(menu) 28n S
.Xp Find&Start(last) 28n S
.Xp Find&Start(N) 28n S
are similar to the
Find&Start
program-command, except that they start at a different place: the start of the menu, the start of
the last view, and the start of the Nth view, respectively.
Searching the menu is a bit special, as the ordinary user cannot do it; however it can be
useful to use
Find&Start(menu)...
to find a menu-button and then to
Select
or
Undo
it.
Searching in the menu does not affect the true marker-bar, which is restored to its previous place after
the menu activity is over, i.e. the user will never see the marker-bar lying in the menu.
.Xp "(The following Find commands can all contain &Marker-bar or &Start(...) or &Start (which is the default), e.g. Find&Marker-bar&Any-replace-button.)" 0n
.Xp Find&Any-replace-button 28n S
finds within the name of any replace-button.
.Xp Find&Context-library(context-name) 28n S
searches for the string S within an occurrence of the specified context.
If the definition of the context has not already been loaded it is looked for in the context-library (or libraries).
(This program-command can be written as
Find&context-name\fR,
in which case the search of the context-library is inhibited; authors should, however, be
careful that this can never lead to an error message when the context is not already loaded.
Such a message would confuse ordinary users.)
.Xp "Find&Enquiry, Find&Ghost" 28n S
searches for the string S within occurrences of enquiries and ghosts, respectively.
(The
Find&Ghost
program-command searches for ghosts even when reader-display options have been set.)
.Xp "Find&Local, Find&Regional, ... , Find&Action" 28n S
searches for the string S within occurrences of button-names.
Note that these program-commands only search within the names of buttons.
.Xp Find&Menu-button 28n S
is an obsolete program-command, now superseded by program-commands such as
Find&Start(menu)&Action.
.Xp Here 28n
places the marker-bar immediately after the button that contains the current program-command-sequence, or, if that button is a glossary-button, at the start of its replacement. To avoid ambiguity, there is a rule that the
Here
command must be the first command in the program-command-sequence (except
that it may follow the
Shyly
or
Comment
or
Set
commands); it is not allowed in a program-command-sequence fed to Guide by another program.
.Xp Is-selected 28n
tests if a replace-button is selected. The marker-bar should lie within
the name of a replace-button -- this will usually be achieved by the program-commands:
Shyly; Find&Any-replace-button "XXX"
where XXX is the name of the required replace-button. If the replace-button is not selected (or if the marker-bar is not within a replace-button) the rest of the current program-command-sequence is ignored. .Xp Message 28n S gives a message to the user. An example is
Message ^/Place marker-bar; then select ^Proceed^/
The string S should always be a setting for the menu, i.e. it should begin
with
^/
.
It will normally contain one button, with a name such as Proceed or OK.
.Xp New&Cover 28n S
is like
New&New-view
(see below), except that the current set of views is covered by the
new material; it can be uncovered again later.
.Xp New&Insert 28n S
is identical to the user selecting New and Insert, and then
typing the string S.
.Xp New&New-view 28n S
is identical to the user selecting New and New-view, and then
typing the string S.
.Xp New&Replace-all 28n S
is identical to the user selecting New and Replace-all, and then
typing the string S.
Filenames within S are taken relative to the embedded-relative-directory, as explained
in the Guide manual page.
.Xp New&Replace-last-view 28n S
is similar to the above, but just replaces the last view.
.Xp Options 28n S
sets the options specified by S.
Currently the only possible value of S is `r': this means that any subsequent
Find
program-commands in the current program-command-sequence should behave as if
the user was in reader-display, i.e. they should only find what the reader would see.
.Xp Output 28n S
outputs the string S on the standard output.
This is particularly useful when Guide has been set going by another tool, and is piping output back to it. (The Output program-command is often followed by a Quit.)
.Xp Quit
is identical to the Quit command in the Guide menu.
.Xp Reader
is identical to the Reader command in the Guide menu.
.Xp Retreat
is the converse of the
Advance
program-command.
The marker-bar must initially be at the start or immediately after the end of a construction.
.Xp Save 28n S
is identical to selecting the Save command with its normal options, and typing
S as the filename.
The filename is taken relative to the user's starting directory.
The view to be saved can be set by the
Set-save-view
command.
If it is required to save in several layers, the
Save
command can be given an argument
-rN
where
rN
is an integer between 1 and 4 that gives the recipe; numbers correspond
to those given in the
Re-configure option of the Save command.
The
-r
argument is followed by a list of files (one for each layer, top layer first), e.g.
Save -r3 annotation.gu original.gu
(If a Save is done in a shy way, the original file is not marked as saved;
thus the user then will be warned if he tries to exit, having edited the source and
not subsequently saved it explicitly.)
.Xp Save&With 28n S
is like the
Save
command, but using its With option.
.Xp Save&Without 28n S
is like the
Save
command, but using its Without option.
.Xp Save&Dump 28n S
is like the
Save
command, but using its Dump option.
.Xp Select
causes the button in which the marker-bar lies to be selected. It is an error
if the marker-bar does not lie within a button.
(It is also an error if the button is already replaced; however, since selecting is usually preceded by a Finding operation that
places the marker-bar within the button to be selected, and since Finding
within a button-name automatically undoes that button, this error is unusual.
Another somewhat esoteric error condition is nested attempts to send
program-command-sequences to Guide from other tools -- one such tool
can try to select a button that runs another such tool!)
.Xp Set 28n S
where S is of the form X=Y, sets the UNIX environment variable X to the string Y.
(This variable can then be used in Guide button-conditions, in nested-elements or in shell-scripts
called from within Guide.) An example of the interactive use of
Set
is:
Set "ENV="/Type the setting required:/
.Xp Set-find-count 28n N
makes subsequent
Find
commands within the current program-command-sequence find the Nth occurrence of the sought string (rather than the first, as is normal).
(N can be an expression, as with the
Set-save-view
program-command.)
.Xp Set-load-request-view 28n N
is a somewhat esoteric command that causes subsequent
New
commands within the current program-command-sequence to act as if they came from view N (where view 0 is the menu).
This can affect the directories that are searched.
.Xp Set-save-view 28n N
records that the integer N (which can, if required, be represented by an expression consisting of numbers
separated by `+' and `-' signs, e.g. 11-8+1) is to be the view-number to be used by subsequent
Save
commands within the current program-command-sequence.
(A negative setting means use the defaults: view 1 for a save of the source, all views for a save of the text as seen.)
.Xp Set-save-width 28n N
records that the integer N is to be used as the line width on subsequent
Save&With
or
Save&Without
commands within the current program-command-sequence.
(N can be an expression, as with the
Set-save-view
program-command.)
.Xp Shyly
causes the rest of the current program-command-sequence to be executed in a shy way.
.Xp Skip-if 28n S
where S is a button-condition, skips the rest of the current program-command-sequence if
S is true. An example of its use is:
Skip-if ?@{COUNT} > 6; . . .
An annoying feature of
Skip-if
arises because nested-elements within the string S are evaluated before
the program-command is parsed.
(This contrasts with nested-elements within normal button-conditions, which
are evaluated while the button-condition is parsed.) As an example, assume
that the environment variable USER has the value SMITH; then
Skip-if ? @{USER} == "JONES";
is equivalent to
Skip-if ? SMITH == "JONES"
which is syntactically wrong since SMITH is not in quotes. The correct way to write the above is
Skip-if ? "@{USER}" == "JONES";
(The problem only arises with string values.) .Xp Tocaller 28n S relays the string S to an external program that called Guide (see below). (In addition to the normal forms of string argument, S can also be either $BARLINE or $VIEWCOUNT. The former gives the relative line number, within the current view, of the marker-bar (the first line is line 0, and -1 means the marker-bar is not set); the latter gives the number of views that exist. However this facility has been now superseded by the availability of the environment variables GUIDEBARLINE and GUIDEVIEWCOUNT.) .Xp Type 28n S behaves as if the user had typed the string S. .Xp Uncover 28n quits from the current view(s), and uncovers the most recently covered set of views; if there are no covered views, gives a beep and does nothing. .Xp Undo 28n S undoes the button named S -- the marker-bar should be lie within the replacement of S, though it may be several levels of replacement deeper. If S is omitted, Guide undoes the deepest button whose replacement contains the marker-bar: the sequence
Here; Undo
is frequently used to undo the replacement containing the current button.
The
Undo
command behaves just like normal undoing in Guide, e.g. unasked replacements can
only be undone when in author-display.
Generally the screen is not repainted until a program-command-sequence has finished.
However, when there is a dialogue with the user (e.g. a string argument that
requires the user to type something) the screen is painted.
This leads to a small problem: normally when Guide paints the screen then, if the
marker-bar is not within the material painted, the marker-bar is deleted.
(For example switching to author-display makes the menu bigger and the document
shorter, and thus the marker-bar may sometimes disappear as a result.) A
disappearing marker-bar would, however, be a big problem to authors of
program-command-sequences, so Guide does remembers it even if it is off-screen.
The user is, of course, free to change the position of the marker-bar, and may
indeed to told to place it by a string in the dialogue, as in our example for the
Message
command above.
A program-command-sequence can be fed to Guide from a separate program. This can occur in one of two ways:
run
constructor attached to a Guide button.
This lets the shell augment the programming language offered by Guide.
We consider these two cases in turn.
The
callguide
program, supplied with Guide, is given a program-command-sequence as argument.
It feeds the program-command-sequence to Guide.
Any string transmitted back by the
Tocaller
command is output on the standard output.
An exit status of 0 is returned if the program-command-sequence was
successfully completed; otherwise a non-zero status is returned -- see
the manual page for
callguide
.
As an example of the use of
Tocaller
the shell command
var=`callguide 'Tocaller /Type the name:/'`
passes the command
Tocaller /Type the name:/
to Guide, and sets
var
to the string typed by the Guide user.
Full examples of shell-scripts that use
callguide
can be seen in the
advanced_button_demo
file that is issued with the Guide library.
The
callguide
program is designed for use from within shell-scripts initiated by Guide.
A separate application can pass a program-command-sequence to Guide by doing the following:
If the application wishes to get information back from Guide, it puts as the first line of /tmp/guidefindN:
#kill(P,S)
where P is the application's PID and S is the signal that Guide should
send to the application on completion.
Guide then executes such a
kill
command when it has finished.
Guide also uses the /tmp/guidefindN file for communicating information
back to the caller.
All strings output by
Tocaller
commands are sent to this file.
The very last byte of this file is the exit status.
It is possible to write a separate application that periodically updates material
(e.g. a clock field) within a Guide document.
As we have said, such an application does best run to execute program-commands
Shyly
in order not to over-distract the user.