Oberon10.Scn.Fnt ZParcElemsAlloc Oberon14m.Scn.Fnt 0Oberon12m.Scn.FntOberon12.Scn.FntV b  Oberon12b.Scn.FntOberon12i.Scn.Fnt^ q Z     Z  ` O  Z @` O ' Z L} n L q  Z Η? Z +9Oberon10i.Scn.FntMath12.Scn.FntI*`;@@   Z@@ t\1Q Z  Q  I p*@+- Z b   Z hi Z b f Z '  Z ? Z@@  Z  & Z  e" Ez  Z ௶ j Z  ^ Z@@ DWGuide to Edit 3.0 (20 Apr 1994) C. Szyperski / M. Hausner Tutorial and Release NotesIntroduction Edit is an extensible text editor for the Oberon system. It is based on a few simple concepts and aims at typical writing tasks, such as memos and reports. It does not try to support a document model, and it is not fully "wysiwyg". To arrive at a rather simple implementation, the few concepts provided have been carried out with all consequences. This should be kept in mind before considering a certain behaviour of the editor to be a "bug". The following tutorial assumes that the reader already knows how to use the Oberon system, especially, how to handle viewers, files, and commands. In a second part, EditTools (a collection of supportive commands) is described. Study of this part can be delayed till special needs occur. Principles A text models a sequence of characters. Besides standard characters, Edit supports special user extensible characters. Such characters, called text elements or simply elements, float in the text just as ordinary characters do. Typical elements support the integration of graphics and the like into texts. A standard extension of elements allows for separating the text into paragraphs. Such elements are called paragraph controls or parc for short. A parc defines the paragraph attributes for all characters following it up to the next parc or the end of the text. Editing Insertion of new characters into the text requires setting the caret left to the character before which to insert, or to the end of the text. The caret can be set by clicking the left mouse key at the desired location. Selecting a stretch of the text corresponds to selecting a range of characters. The visible selection extends from the beginning of the first selected character to the beginning of the first character behind the selection or the end of the text. Hence, selections always reflect the exact area which is affected when changing or deleting. A stretch of text is selected by dragging the the right mouse key over the characters to be selected. While setting the caret or selecting a stretch of text, other mouse keys can be interclicked to execute further editor functions. Interclicking means clicking a mouse key while another one is pressed. The following interclicks are interpreted by a text viewer: buttons effect left + middle copies the most recent selection to the place where the caret will be set on release of the left key left + right copies the attributes of the character to the right of the caret to the most recent selection right + left deletes the selection being tracked on release of the right key right + middle copies the selection being tracked to the caret location on release of the right key left + middle + right cancels an erroneous interclick Clicking the mouse in the scroll bar has the following effects: buttons effect left forward scroll. The line at the mouse position will be moved to the top of the viewer right backwards scroll. The line at the mouse position will be moved to the bottom of the viewer middle absolute positioning middle + left scroll to end of text middle + right scroll to beginning of text The cursor left/right keys move the caret. To support editing indented text (like programs), the Linefeed key can be used instead of Carriage-Return. This will indent the next line to the same level as the previous paragraph. The cursor left/right keys will shift indented text if it is selected in the focus viewer. Furthermore, when extending a selection over two consecutive viewers, Edit adds visual feedback. This avoids the danger of extending a selection by mistake and then deleting or copying a far larger stretch of text than was intended. See below for a description of commands that further support basic editing. Some elements support inplace editing. To use this feature, an element must be focussed by clicking into its area using the left mouse button. A focussed element is highlighted using a grey frame. As long as the focus remains set, mouse clicks in the area of the element are interpreted to allow for inplace editing. In order to insert a parc into a text, place the caret at the appropriate position and press BREAK. This will copy the parc above the caret position (or the default parc if there is none above). Pressing Shift-BREAK inserts a parc which forces a page break (attribute break=before). Using the command Edit.Parcs parcs can be made visible or hidden again. If visible, a parc is displayed as a grey separation line corresponding to the width set for that paragraph. At the left and right end of that separation line, one or two rectangular handles signal the formatting mode of the paragraph. The handles may either be shown solid or hollow. A solid handle at the left end means left-justified text, a solid handle at the right means right-justified text. Two solid handles signal fully justified text. If both handles are hollow, the text is centered. Below the separation line, tabulator stops are indicated by tab marks. Above the separation line, the first line indentation is indicated by the first mark. Parcs which force a page break are shown with a solid separation line. A parc defines a special behaviour for middle-button mouse clicks. It has several sensitive areas. The following table shows how various middle mouse button clicks and interclicks affect the paragraph attributes bound to a parc. Again, see the commands below for further manipulations of parcs. where buttons effect left handle middle move left margin right handle middle move right margin above separation line, first mark hit middle move first line indentation mark above separation line, towards left end middle toggle left flush formatting above separation line, towards right end middle toggle right flush formatting below separation line, no tab mark hit middle create new tab below separation line, tab mark hit middle move tab below separation line, tab mark hit middle + left delete tab below separation line, tab mark hit middle + right move tab and all subsequent tabs in synch Printing When printing a text, Edit reformats individual paragraphs for the printer. Edit preserves all user setable measures, while individual words may be placed differently. This allows for optimal display of texts on the screen, while at the same time fully exploiting the printer resolution. Hence, it should not be tried to affect the placing of individual words by inserting additional blanks or the like! Furthermore, Edit ignores all empty space at the beginning of a page except when preceded by a parc with enforced page break attribute. White space in this sense are empty lines (a single blank makes a line non-empty!) and lead-space defined by a parc. Refer to the print command description below for details on how to initiate a printout. For two columns the width of a column is set by the corresponding parc, while the horizontal origin x of the right column is computed based on the body width w selected for printing: xrightCol = xleftCol + 0.57wbody + 3.5mm. The actual gap between the left and the right column then is: gap = (xrightCol + leftrightCol) - (xleftCol + leftleftCol + widthleftCol). In order to achieve good results, the Lm3 metrics files for the used font families should be available. For example, when using the fonts Oberon12, Math12, Oberon14, and LetterHead, the metrics files Oberon.Lm3.Fnt, Math.Lm3.Fnt, and LetterHead.Lm3.Fnt are required. If a metrics file for a used font is missing, the printer metrics are estimated using a simple heuristics based on the screen font metrics. Beware: this leads to at most draft quality of the printed text. Commands in the Viewer Menu Edit.Search Takes the most recent selection as search argument. If the selection is older than the latest one used for Edit.Search, the previously set search argument will be used. Edit.Search starts searching at the current caret position, or at the beginning of the text, if no caret is set. When starting the search behind the last occurrence of the search pattern, the caret is removed. Edit.Replace Takes the most recent selection as replacement argument. If the selection is older than the latest one used for Edit.Replace, the previously set replacement argument will be used. Edit.Replace verifies that the pattern left to the current caret position matches the current search argument. If so, it is replaced and Edit.Replace automatically searches for the next occurrence. Edit.Replace does not wrap around when searching. Edit.ReplaceAll Edit.ReplaceAll operates much the same way as Edit.Replace does. Additionally, the replacing process is carried on to the end of the text. Edit.ReplaceAll does not wrap around when searching. Edit.Parcs If parcs are hidden (the default), makes them visible. Vice versa, if parcs are visible, hides them. Edit.Store Stores the text. After completing, Edit.Store writes out the number of characters in the text. Whenever the text displayed in a text viewer has been changed but not yet stored, the menu bar contains an exclamation mark following the Edit.Store command. Commands in the Edit Tool The following commands are supported by Edit. Generally, the standard Edit tool contains several examples on how to use the Edit commands, most of which should be self-explaining. For each command, the parameters directly following the command are given. Furthermore, most of the commands take further implicit parameters, like the current selection, the current focus (the caret), and the selection in the currently marked viewer. Such parameters are also listed below. The selection symbol "^" adds a level of indirection by taking the explicit parameters of the command from the current selection. Explicit parameters may be names (sequences of characters starting with a letter, followed by letters, digits, or periods), strings (sequence of characters enclosed by quotes), or numbers (sequences of characters starting with a minus or a digit, followed by digits). command explicit parameters implicit parameters Edit.Open ("^" | name | string) Opens a text viewer displaying the named text. Names that do not follow the Oberon naming convention may be specified as strings, i.e. written between double quotes. Edit.Print server-name ("^" | "*" {option} | {name {option}} "~") Prints a list of texts. The print options are explained in a separate table below. Unless specified otherwise (using the /p option), Edit.Print will assign consecutive page numbers to all texts printed with a single print command. As feedback, Edit.Print writes the name and the number of copies of each printed text to the system log. Also, a period is written to the log for each page sent to the printer. A quote is written for each page formatted but skipped. Edit.Recall caret Inserts the most recently deleted text stretch at the current caret position. Edit.ClearReplaceBuffer Clears the replace buffer. Afterwards Edit.Replace(All) can be used to delete found patterns, i.e. to replace them by the empty pattern. Edit.InsertParc caret Inserts a new default parc at the current caret position. Edit.Locate selection marked viewer Locates a character position and makes it visible in the marked viewer. Edit.Show ("^" | name) Tries to interpret name as module.identifier. If possible, opens text module.Mod, searches for identifier, and displays the text with the caret set behind the first occurence of identifier. The search buffer is properly set, such that further occurences can be retrieved using Edit.Search as usually. Edit.ChangeFont ("^" | name) selection Change the font attribute of the selected characters in the marked viewer. If the font name is referred to with '^', it is read from the selection in the viewer from which Edit.ChangeFont was called. Edit.ChangeColor ("^" | number) selection Change the color attribute of the selected characters in the marked viewer. If the color number is referred to with '^', it is read from the selection in the viewer from which Edit.ChangeColor was called. (Has no visible effect on monochrome monitors, on color monitors; 0 is the background and 15 the foreground color.) Edit.ChangeOffset ("^" | number) selection Change the vertical offset attribute of the selected characters in the marked viewer (-128..127). The offset is specified in 1/64th of the font height of the affected character. If the offset is referred to with '^', it is read from the selection in the viewer from which Edit.ChangeOffset was called. Edit.Set ("^" | attribute-name [values] ) selected parc Sets paragraph attribute bound to the selected parc. If the attribute is referred to with '^', it is read from the selection in the viewer from which Edit.Set was called. The paragraph attributes are explained in a separate table below. If multiple parcs have been selected, all will be affected. Edit.Get ("^" | attribute-name) selected parc Gets paragraph attributes bound to the selected parc. If the attribute is referred to with '^', it is read from the selection in the viewer from which Edit.Get was called. The paragraph attributes are the same as for Edit.Set. If no special paragraph attribute is selected, all attributes will be shown. Print Options option function "/a" alternating pages - different page formatting for even and odd page numbers "/c" number request a certain number of copies to be printed (1..9) "/f" name select font other than the system default font for headers and page numbers "/h" request a default header (file name plus print date) on each page "/h" string request the specified header on each page "/m" "h" {number} override default positioning of header - up to three numbers are accepted: offset from the left, offset from the bottom, and width of the header, resp. (defaults: 150 2800 1650, each in 1/10 mm) "/m" "b" {number} override default positioning of text body - up to four numbers are accepted: offset from the left, offset from the bottom, width, and height of the body, resp. (defaults: 150 150 1650 2600, each in 1/10 mm) "/p" number start page numbering at a certain number (otherwise it starts at 0) "/p" "f" suppress page number on first page "/p" "n" suppress page numbers "/p" "r" use Roman instead of Arab numerals (for page numbers 1..30, only) "/s" number [number] select page(s) to print (the numbering corresponds to the one set by /p) Note: in Oberon systems running on Unix machines the backslash character "\" is used to specify print options. Paragraph Attributes All numerical values are to be specified in 1/10 mm units (e.g. the value 150 corresponds to 1.5 cm). attribute value(s) default function "adjust" block | center | left | right left formatting mode "break" before | normal normal if before, force page break immediately before parc "columns" 1 | 2 1 one or two column casting of paragraph "first" number | "default" 0 first line indentation "grid" on | off off line grid "lead" name | number | "default" 0 leading paragraph space (name specifies model font) "left" number | "default" 0 left margin "right" number | "default" 1650 right margin "line" name | number | "default" 34 (Oberon10) minimal line height (name specifies model font) "tabs" ("*" number | {number} "~") ~ tab spacing (every n, or enumerated) "width" number | "default" 1650 maximal line width The line spacing model assumes a minimal line height for each paragraph. If a line exceeds its minimal line height, it is automatically adjusted to avoid clutter between it and the line above it. If the line grid is turned on for that paragraph, the line is adjusted to an integer multiple of the minimal line height. Advise: In order to reach a typographically sound layout, in most cases a single line height should be selected for all paragraphs of the text. To get good results when combining a font for body text with larger ones for titles and section headings and smaller ones for captions, it is useful to set the line height to the body font and turn the line grid on. In most cases, it is preferable to set line height and paragraph leadings using the name of the predominant font ("model font"). Part II - Edit Tools EditTools is a collection of utility commands. command explicit parameters implicit parameters EditTools.SearchDiff [ "/w" ] marked viewer Takes the marked viewer and the viewer immediately above it, both of which must hold text frames. Takes a selection to indicate a position in both texts; if no selection is present the begin of the text is taken. Starting from the two indicated positions, SearchDiff searches for the next position where the two texts do not match. If such a position is found it is displayed in both viewers and selections are set to allow for continued searching. If no mismatch is found, selections are removed. If the option "w" is indicated, white space characters are ignored when comparing the texts. EditTools.ShowAliens marked viewer Searches the marked text for undefined elements. Such elements occur, if a text is opened while some defining modules of extended elements are not available. Edit displays undefined elements uniformly as an empty frame. EditTools.ShowAliens lists the position of such elements, as well as the names of the missing modules. Note that undefined elements can be selected, copied and deleted freely. As soon as the missing module becomes available, it is sufficient to reopen affected texts and the elements will again behave as originally intended. EditTools.GetAttr ("*" | "@") marked viewer or selection Gets textual attributes of the selected text: module name of elements, font names, colors, and vertical offsets. All combinations of attributes are listed. Alternatively, a text may be marked leading to a list of all attribute combinations used in the whole text. If a single character is selected, GetAttr also displays the character's ASCII code. EditTools.SearchAttr ("^" | {tag value}) caret, selection Uses a combination of attributes and searches starting at the current caret position, or at the beginning of the focus text, if no caret is set. If a character (or element) in the text uses just this combination, it is displayed and the caret is set behind it. Otherwise, if nothing is found, the caret disappears. The lines output by GetAttr can readily be used as input for SearchAttr. The following table shows valid attribute tags and value ranges: tag value elem module name of a module implementing the corresponding element font font name col color (typically a value in the range 0..15, normally 15) off vertical displacement (range -128..127, in 1/64 of fount height, normally 0) ascii value in (extended) ASCII character set (0..255) EditTools.IncSize ("^" | number) selection Increment font sizes in selected range (negative increments may be used to decrement sizes). If a computed font is not available, the old font is retained. EditTools.ChangeSize ("^" | {number "=>" number} "~") selection Change font sizes absolutely within the selected range. If a computed font is not available, the old font is retained. The source number may be replaced by a question mark to indicate that all fonts in the selected range should be resized to the destination number. EditTools.ChangeFamily ("^" | {name "=>" name} "~") selection Change font families within the selected range. If a computed font is not available, the old font is retained. The source name may be a question mark to indicate that all fonts in the selected range should be renamed to the destination name. EditTools.ChangeStyle ("^" | {style "=>" style} "~") selection Change font styles within the selected range. If a computed font is not available, the old font is retained. Font styles are denoted by characters, where "." denotes the plain style. For example, "b" denotes the bold style. The source style may be a question mark to indicate that all fonts in the selected range should be changed to the destination style. EditTools.Change ("^" | {name "=>" name} "~") selection Change fonts within the selected range. If a font is not available, the old font is retained. EditTools.Words ("*" | "^" | {name} "~") Counts Carriage Returns, characters, elements, and words in the listed files. Note: For a source listing, the number of Carriage Returns corresponds to the number of lines (incl. empty lines). For documents, the number of Carriage Returns corresponds to the number of paragraphs (incl. empty ones). EditTools.Cleanup ("*" | "^" | {name} "~") Scans a text and removes alien and ill-sized elements. EditTools.RemoveElems ("*" | "@") marked viewer or selection Scans a marked text or the selection and removes all found elements. EditTools.ToAscii ("*" | "@") marked viewer or selection Scans a marked text or the selection and replaces the characters given in the table below as follows:  Character Replacement TAB two spaces , , , , , Ae, Oe, Ue, ae, oe, ue , , a , , , e , , i , o , u , c, n German double s ss  EditTools.StoreAscii ("^" | ("*" | name)) marked viewer or selection Stores the marked text as a plain ASCII file, i.e. stripping all formatting information and removing all elements. Upon completion the number of bytes taken by the created file is written to the system log. EditTools.Refresh ("*") marked viewer Reorganizes the internal structure of the text in the marked text frame. Then causes all frames displaying that text to refresh. Useful when after a long editing session a text got too fragmented, i.e. the editor speed is slowing down. When done, refresh displays the number of bytes that a store of the text would take. EditTools.LocateLine ("^" | number) marked viewer, selection Locates the line with the given line number. Paragraphs spanning multiple physical lines are treated as a single (logical) line. Empty lines are counted. EditTools.InsertCR (number ("*" | "@")) marked viewer, selection Breaks text into individual lines of at most number characters by inserting carriage returns. Words are not splitted unless they are longer than number characters. EditTools.RemoveCR ("*" | "@") marked viewer, selection Removes carriage returns at the end of lines. Does not remove carriage returns at the end of empty lines, i.e. lines containing no characters other than a carriage return. Elements For a documentation of existing text elements, cf. Elem.Guide.Text .