s Syntax10.Scn.Fnt ZParcElemsAlloc Syntax14m.Scn.Fnt 1Syntax12m.Scn.FntSyntax12.Scn.FntV b  Syntax12b.Scn.FntSyntax12i.Scn.Fnt^ q Z        Z @` O ' Z L}  % Z  +9Syntax10i.Scn.FntMath12.Scn.FntI*`;@@  @@ t\1Q Z  Q  I p;< b   hi b f '  I@@   &  e" Ez  Z ௶ j  ^ Z@@ DVGuide to Edit 3.0 (28 Sept 1993) 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). Using the command Edit.Parcs parcs can be made visible or hidden again. If visible, a parc is displayed as a separation line corresponding to the width set for that paragraph. Above that separation line, one or two marks signal the formatting mode of the paragraph: a single mark at the very left, in the middle, or at the very right indicates left flush, centered, or right flush formatting, respectively. Two marks at both ends indicate block (fully justified) formatting. Below the separation line, set tabs are indicated by marks. Pressing Shift-BREAK inserts a parc which forces a page break (attribute break=before). Such parcs are displayed using a solid separation line. A parc defines a special behaviour for middle-button mouse clicks. It has two separate sensitive areas. One above and one below the separation line. 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 above separation line, left end middle inset left margin above separation line, left end middle + right symmetric inset of left & right margin above separation line, right end middle inset right margin above separation line, right end middle + right symmetric inset of left & right margin above separation line, left end middle + left set first line indentation mark above separation line, first mark hit middle move first line indentation mark above separation line, towards left end middle left flush formatting above separation line, in the middle middle centered formatting above separation line, towards right end middle right flush formatting above separation line middle + left block formatting above separation line middle + right toggle one/two column 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 + right move tab and all subsequent tabs in synch below separation line, tab mark hit middle + left delete tab 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 Syntax12, Math12, Syntax14, and LetterHead, the metrics files Syntax.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 right 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 in marked viewer Change the font attribute of the selected characters in the marked viewer. Edit.ChangeColor ("^" | number) selection in marked viewer Change the color attribute of the selected characters in the marked viewer. (Has no visible effect on monochrome monitors, on color monitors; 0 is the background and 15 the foreground color.) Edit.ChangeOffset ("^" | number) selection in marked viewer 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. Edit.Set ("^" | {attribute-name [values]}) selected parc in marked viewer Sets paragraph attributes bound to the selected parc. 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 in marked viewer Gets paragraph attributes bound to the selected parc. 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 (Syntax10) 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 (default), 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 .