M Origami User Manual J An universal folding editor J _M_a_r_t_i_n _G_r_e_e_n J _C_h_a_r_l_i_e _L_a_w_r_e_n_c_e J _M_i_c_h_a_e_l _H_a_a_r_d_t J _W_o_l_f_g_a_n_g _S_t_u_m_v_o_l_l J _M_i_c_h_a_e_l _S_c_h_w_i_n_g_e_n J Aachen, July 1991 GOrigami User Guide HMichael Haardt Auf der Hoern 40 5100 Aachen Germany July 23, 1991 - 2 - J _A_B_S_T_R_A_C_T J This document explains the principles of folding edi- tors in general, because most people have never used such an editor. It gives an example of an Origami editing session to show the advantages of folding program sources. It then explains how to compile and install Origami. All functions of Origami are listed and described. It never refers to concrete keys, because the Emacs-like and the TDS keybind- ings are completely different. This document explains the Origami control language (OCL) detail, because very compli- cated editor commands can be created. _1. _I_n_t_r_o_d_u_c_t_i_o_n _1._1. _O_r_i_g_a_m_i Origami is a `folding editor', similar to, and inspired by, the editor included in the Inmos TDS (Transputer Development System). Those of us who have become familiar with the TDS editor have long bemoaned the lack of a similar editor for use with other languages, for example Pascal and C. Origami is not a word processor (although many of its features would be useful in a word processor), but it comes into its own as a program editor for structured languages and documents. The structuring of the code or text is obvious from the screen display (if Origami is sensibly used!), although no actual code may be visible. Existing files, not produced using Origami, may be imported into Origami, and then folded up for future use, and ease of development. These files may be further edited either using Origami or some other editor (if you can bear to use one after Origami!), and compiled in the normal way. _1._2. _T_h_e _F_o_l_d_i_n_g _E_d_i_t_o_r A `folding editor' extends the principle of tree structured directories to editing text files. This allows the simultaneous display of large amounts of text by `folding' sections of text away behind a descriptive heading. This results in a tree structure very similar to a sub- directory structure of, for example, UNIX. By suitable structuring of a text it should be possible, in most circumstances, to ensure that no display exceeds a single screen at any time. To access text which is folded away you can either ENTER the con- taining fold, in which case the contents of the fold and its header are the only displayed text, or you can OPEN the fold, in which case the contents are displayed in the context of the surrounding text. J July 23, 1991 - 3 - The advantage of this system is that it eliminates the need for seemingly endless paging through long files to find the section of interest, allowing you to move down the tree structure, following the (hopefully) descriptive headers to locate the text you require. _1._3. _E_x_a_m_p_l_e_s _o_f _O_r_i_g_a_m_i _F_o_l_d_i_n_g As an example, a Pascal file might look like this at the top level (eg immediately after starting Origami): program test; ... CONSTs ... TYPEs ... VARs ... procedures ... main body of code OPENing the VARs fold might lead to the following display: program test; ... CONSTs ... TYPEs {{{ VARs VAR i : integer; x : real; }}} ... procedures ... main body of code ENTERing the procedures fold might give: {{{ procedures ... statistical procedures ... string handling procedures ... procedure user_input }}} Each of these folds can be ENTERed further until actual code is reached - for example if we ENTER the `procedure user_input' fold we might find: {{{ procedure user_input procedure user_input(prompt : str_type; var reply : str_type); ... local declarations ... local procedures begin repeat write(prompt); readln(reply); until verify_reply(reply); end; }}} July 23, 1991 - 4 - _2. _I_n_s_t_a_l_l_i_n_g _O_r_i_g_a_m_i _2._1. _C_o_m_p_i_l_i_n_g _O_r_i_g_a_m_i Before compiling Origami, you have to generate makefiles for your machine. There are cpp-makefiles with explanations on how to do this at their heads. If you port Origami to a new machine, please change the cpp-makefile and send me cdiffs for everything. Origami tries to be POSIX compatible. Not BSD, not v7, not system V. POSIX! After compil- ing everything, copy the binaries to /usr/local/bin. I suggest to copy the keybind-files and the learn directory to a public readable direc- tory, where every user can get them to modify them for his personal use. At last, you have to make your choice, which keybindings you personally want to use. Read the next sections to see how to install them. _2._2. _S_t_a_r_t_u_p-_f_i_l_e_s Origami uses startup-files to determine its behaviour. Every used com- mand must be bound to keyboard-inputs explicitly. You can also declare ``user defined commands''. These features are explained in the chapter ``Programming in OCL''. Used startup-files and their meanings: $HOME/.origamirc This file contains the keybinding table and all user defined com- mands. Every command you want to use is bound to a sequence of keyboard inputs. Origami won't start missing the file ``$HOME/.origamirc''. $HOME/.origamibind This file contains a help, decribing the keysequences for each bound command. Its displayed when calling the command ``describe- bindings''. $HOME/.origamihelp There is no standardfile for it. It's displayed using the special origami command ``O_HELP''. You can use it for ``user-defined- helps'' (all the stuff you always forget). The namebase ``.origami'' in ``$HOME/.origamirc'', ``$HOME/.origamibind'' and ``$HOME/.origamihelp'' is generated using the commandname (argv[0]) and the following rules: j.J If there are any path-limiters ``/'', only the string following the last ``/'' is used. j.J All ``.'' at begin of the remaining string are removed. j.J The startupfilenames are generated by adding ``$HOME/.'' at front and ``rc'', ``bind'' or ``help'' at end of the string. This way of getting the startup-files makes it possibly to use origami with several startup-files. Renaming the binary or using a link July 23, 1991 - 5 - switches to other startup-files. For example: origami using a normal text-installation. No special commands. Uses ``$HOME/.origamirc'', ... morigami using special mail-macros. Uses ``$HOME/.morigamirc'', ... To use such an environment, create a link named ``morigami'' and gen- erate startup-files ``$HOME/.morigamirc``, ... containing bindings and macros needed for mailing. _2._3. _K_e_y_b_i_n_d_i_n_g_s _2._3._1. _S_y_n_o_p_s_i_s _o_f _K_e_y_b_i_n_d The keybind program compiles a keybinding-file into the startupfiles ``$HOME/.origamirc'' and ``$HOME/.origamibind''. Its synopsis is: keybind [-hlsv?] [-o] _k_e_y_b_i_n_d_i_n_g-_f_i_l_e keybind -k Options: -s the entries in bind are sorted -o the outputfiles are named $HOME/rc and $HOME/bind instead of $HOME/.origamirc etc. Useful for using origami via link, renamed binary or with commandline option ``-k''. -k display the names of the origami function with token-value number. This is useful, if keybind complains about your keybinding (dif- ferent functions bound to the same keysequence etc.). -? display usage -h same -l list all keywords known in origami and keybind. -v during compilation of the sourcefile print information about needed resources. Be careful with keybind, it overwrites existing files! _2._3._2. _T_h_e _k_e_y_b_i_n_d_i_n_g _f_i_l_e J This file contains a list of ASCII rules to bind keysequences to Origami functions. It looks like LISP, but it isn't LISP. The language is named OCL (Origami control language). This section describes all J July 23, 1991 - 6 - functions used for binding functions to keys. OCL is described in a later chapter, because it is not necessary for keybindings and it is very powerful, perhaps too powerful for learning it while installing Origami. J (defbinding ) Defines a name for the binding, which is displayed in the statusline of Origami. Multiple usage of this command is not allowed. The name is limited to 16 characters. J (keybind ) The Origami-operation named is bound to the keyboard input . The file .origamibind contains an entry `` '' J (alias ) The keyboard input can be named $ in the follow- ing definitions. Using $ puts name in the file .origamibind instead of the sequence of keys. J <_n_a_m_e> is a normal identifier J A <_k_e_y_s_e_q_u_e_n_c_e> is a sequence of enclosed in parentheses. J <_k_e_y> specifies a single key (or two keys, because M-"a requires two keystrokes): "_x is a single character _C-_X is control-x _C-? is the delete-key (127) _M-"_x means Meta-key (ESC) followed by x (case-sensitive) _M-_C-_X META-control-x $_n_a_m_e represents the keys defined in (alias name ..) J Newlines can be used anywhere in the text between syntactical struc- tures. Comments can be put in the same way. A comment starts with ``;'' and ends at the end of the line. The braces ``{'' and ``}'' have the same effect as ``;'', so you can use origami with language None and filed-folds are included automatically. These aliases can be used without declaration: J July 23, 1991 - 7 - $esc = escape-key = 27 $tab = tab-key = 9 $return = return-key = 13 (yes!) The following default aliases are available, if your terminal has the termcap capabilities in parentheses: $backspace (kb), $backtab (kB), $rubout (kD), $clreol (kE), $delline (kL), $home (kh), $end (kH), $up (ku), $down (kd), $left (kl), $right (kr), $prev_page (kN), $next_page (kP) $f0 (k0), $f1 (k1), $f2 (k2), $f3 (k3), $f4 (k4), $f5 (k5), $f6 (k6), $f7 (k7), $f8 (k8), $f9 (k9), $f10 (k;) Your termcap(5) manual explains all capabilities in detail. The above keys mentioned do not represent all capabilities, but those which are frequently used. _2._3._3. _E_x_a_m_p_l_e The following examples are only written to explain the syntax. They will not really work, because you will not be able to move the cursor or even quit Origami. ; This is a simple keybind-file (keybind newline-and-indent C-M) The operation `newline-and-indent' is activated through C-M. The key- bindinghelp contains `newline-and-indent C-M'. You can achieve the same keybinding by using an alias: ; This keybinding uses alias (alias return C-M) (keybind newline-and-indent $return) The operation `newline-and-indent' is also activated through C-M, but the keybinding help contains now `newline-and-indent return'. _2._4. _R_e_q_u_i_r_e_d _t_e_r_m_c_a_p _c_a_p_a_b_i_l_i_t_i_e_s Origami uses the termcap database. It requires a few capabilities to work. It does not need intelligent terminals. The following capabili- ties are required: cm cursor motion ce clear to end of line cd clear to end of display co number of columns li number of lines The following capabilities are optional: July 23, 1991 - 8 - ti termcap usage initialization te termcap usage end al add line dl delete line so stand out se standout end sg standout glitch _2._5. _L_i_m_i_t_a_t_i_o_n_s _o_f _O_r_i_g_a_m_i Origami stores the complete file in memory while editing which limits the size of files to 24 kByte on PC MINIX 1.5.10. The length of a line is limited to 256 characters, and the depth of folding is limited to 256. When reading files, longer lines are splitted. Indenting folds may generate long lines and this case isn't handled correct. Origami expands tab characters to blanks. You should never edit Makefiles with Origami, because make needs tab characters. Otherwise, it is unable to work. In my opinion, this is a (documented!) bug in make. If your file contains `{{{', `:::', `...' or `}}}', Origami will think of them as folding marks! Origami may die on such things. There is a problem editing ``C''-files, if you use the preprocessor-mark ``#'' within the fold-structure. Origami only allows input, when the current position is behind current indentation. Use option -p to change the position of leading ``#'' while writing or reading files. If Origami is reading a file or a pipe, you cannot abort it. So you cannot abort the entering of a filed fold. _3. _U_s_i_n_g _O_r_i_g_a_m_i _3._1. _G_e_t_t_i_n_g _S_t_a_r_t_e_d At this point, you have the choice either to read the next chapters about using Origami or to use the tutorial to learn by doing. This tutorial is similar to the well-known teach-emacs tutorial. You need a copy of the learn directory. Change to this directory and type start-me . This tutorial must be used in Emacs-mode. It is assumed, that Origami is installed and ready to use on your system. It is invoked by typing `origami' after the system prompt. Filenames may be typed after `origami' - if this is not done a prompt for a filename will be issued. If the file being read contains tab characters, Origami will ask for the tab size in order to preserve your formatting. If you have no write permissions for the specified file, Origami will switch to view- only mode. Look at the manual page for advanced command line options. July 23, 1991 - 9 - _3._2. _T_h_e _S_c_r_e_e_n _F_o_r_m_a_t On starting an Origami session, a status line appears near the bottom of the screen. This line will remain throughout your edit, and any prompts or warnings issued by the editor will appear below this line. If you started typing a key sequence bound to a command, this sequence will be displayed under the status line, too. If the second character of the line is a star, your file contains unsaved changes. The current language and the active modes are indicated in parentheses: Folding/F is displayed during creating a fold. DefMac/D is displayed during defining a keyboardmacro. ExMac/E is displayed during the execution of a macro (keyboard or fix). View/V is displayed if origami is in view-only mode. Over/O Origami is in overwrite-mode. ArgRep/R Origami is in argument-repeat-mode. AutoSave/S Origami is in auto-save-mode. Origami will save your files periodically. The short forms are used if the statusline is too long. If there is a name defined in your keybinding file, it is displayed to the left of the language indicator. If the filename is to long to be displayed in the statusline, origami tries to cut the path and displays ``...'' instead of the missing part of the path. _3._3. _T_h_e _E_d_i_t_o_r _B_u_f_f_e_r_s There are three buffers in Origami. The `move buffer' that contains up to one textline, the `pick buffer' in which several lines can be accumu- lated before inserting them back into the file, and the `delete buffer', which holds the last deleted line (in each case a line can be a closed fold, with all its contents). The operations of these buffers in Ori- gami are slightly different from TDS - move, delete and pick buffers are lost on exit from Origami. _3._4. _P_r_o_c_e_s_s_i_n_g _O_r_i_g_a_m_i _F_i_l_e_s If a saved file should pass a particular compiler, the fold structure must appear to the compiler as comments. As comments differ from one language to another, this means choosing the language before saving a new file for the first time, although on reading a file back into Ori- gami the language type is retained (provided the file contained at least one fold). As a consequence of this you should take care not to include strings which the compiler would recognise as comments within the fold header, as this will lead to nested comments which are not allowed in some languages. July 23, 1991 - 10 - Origami knows the languages None, Occam, Pascal, C, Lisp, Roff, Fortran, TeX, Script, User and Inmos. You can specify your own comment strings using language User. Inmos allows to edit files generated by Tds and MultiTool without converting them. Script is useful for sh, csh, remind etc. _4. _A_l_l _O_r_i_g_a_m_i _f_u_n_c_t_i_o_n_s This chapter lists all Origami functions with their keybind names. Most of them have an Emacs-like and a TDS name. If you want to create a new keybinding, regard the Emacs-like and the TDS binding as examples. _4._1. _M_o_v_i_n_g _a_r_o_u_n_d backward-character, O_LEFT forward-character, O_RIGHT previous-line, O_UP next-line, O_DOWN beginning-of-line, O_START_OF_LINE end-of-line, O_END_OF_LINE backward-word, O_WORD_LEFT forward-word, O_WORD_RIGHT previous-page, O_PAGE_UP next-page, O_PAGE_DOWN beginning-of-fold, O_TOP_OF_FOLD Moves to the beginning of the entered fold. end-of-fold, O_BOT_OF_FOLD Moves to the end of the entered fold goto-line, O_GOTO_LINE Prompts for a line number and moves cursor to this line. If needed, Origami opens closed folds to reach this line. Warning: goto-line counts lines from the beginning of an entered fold. This may be not the beginning of the file. _4._2. _F_o_l_d_i_n_g open-fold, O_OPEN_FOLD July 23, 1991 - 11 - Open fold, and show the contents in the context of the current level. You can not open file-folds, only entering them is allowed. close-fold, O_CLOSE_FOLD If the cursor is located within an opened fold, close this fold. enter-fold, O_ENTER_FOLD Enter the fold at the current line. Entering a filed-fold saves the current file. exit-fold, O_EXIT_FOLD Exit fold. Exiting a filed fold saves it. unfold-fold, O_REMOVE_FOLD Remove fold at the current line - deletes the fold structure and inserts the contents of the fold instead. create-fold, O_CREATE_FOLD Create fold. Use twice - first to indicate the top of a new fold, then to indicate the bottom of it. Lines to be included within the fold must not be indented less than the fold itself. Several other keys are disabled while Create Fold is in operation. create-auto-fold, O_AUTO_FOLD Autofold: takes all lines to the first blank line, folds them up, inserts the first line as the fold header, and positions the cursor on the next non-blank line. auto-header, O_FIRST_LINE_TO_FOLD_HEADER When the cursor is on a closed fold this key will copy the first line enclosed by that fold onto the fold line. toggle-create-file-fold, O_FILE_FOLD File (create new file) or unfile a fold. Creating a file writes the contents of the fold into a new file named by the fold-comment (up to the first whitespace). Unlike TDS origami does not create a new filename, if the chosen one is already used. It doesn't matter, if you change the fold-comment after fil- ing a fold, because the filename is stored internally. Unfile a filed-fold removes the link and puts the file-contents into the text. Unlike TDS origami doesn't remove the file. open-file-fold, O_ATTACH_FILE Attach a file to a fold. This function open a existing file instead of creating a new one (and thus differs from O_FILE_FOLD). The July 23, 1991 - 12 - filename is taken from the comment of the empty fold the cursor is placed on. The filename begins behind the foldmark and ends at the first whitespace. The rest of the line has no influence on the attach. After attaching files you can change the fold-header. Fileinformation are stored internally. _4._3. _E_d_i_t_i_n_g delete-to-end-of-line, O_DEL_TO_EOL Delete to end of line. There is no `undo' for this operation. delete-line, O_DEL_LINE Transfers the current line to the `delete buffer', and overwrite the old contents of the delete buffer. undo-delete-line, O_UNDEL_LINE Transfers the line currently stored in the delete buffer back into the file before the current line. This can be done for exact one line. delete-character, O_DEL_CHAR_RIGHT Delete character under the cursor. If the cursor was at the right margin, the next line will be appended to this line. delete-previous-character, O_DELETE Deletes the character to the left of the cursor. If the cursor was at the left margin, this line will be appended to the previous line. undo-delete-character Undeletes the last deleted character. Until the next ``O_DELETE'' or ``O_DEL_CHAR_RIGHT'' the character inserted in the text is always the same. transpose-characters transposes the character left of the cursor with the character under the cursor and moves the cursor right one character. case-word-capitalize Capitalizes the character under the cursor and puts the rest of the word to lower case. If the character under cursor is no letter, nothing happens, otherwise it moves to the next non-letter after the word. case-word-upper July 23, 1991 - 13 - Same as case-word-capitalize, but changes all letters to capitals. case-word-lower Same as case-word-capitalize, but changes all letters to small ones. O_TOGGLE_CASE Characters under the cursor change their case. newline-and-indent, O_RETURN Opens the line at cursor position and indents the right part like the left part. This works for fold comments only at end of line. kill-line, O_PICK Removes a line from the file and adds it to the end of the `pick buffer'. Note that the `pick buffer' is lost on exiting Origami, unlike TDS. copy-to-kill-buffer, O_COPY_PICK Copies a line to the end of the `pick buffer' without deleting it from the file. Note that the `pick buffer' is lost on exiting Ori- gami, unlike TDS. fold-kill-buffer, O_PUT_PICK Places the `pick buffer' before the current line. move-line, O_MOVE If the move buffer is empty, the current line from the file is moved to the `move buffer'. Otherwise the `move buffer' is inserted before the current line. Note that the `move buffer' is lost on exiting Origami, unlike TDS. double-line, O_COPY Duplicates the current line in the file. Lines containing filed- folds cannot be duplicated. _4._4. _S_e_a_r_c_h _a_n_d _r_e_p_l_a_c_e search-forward, O_FIND Prompts for a search string and displays next occurence. An empty search string uses the last search string. search-reverse, O_FIND_REVERSE Same as search-forward, but searches backward. July 23, 1991 - 14 - replace-string Asks for a search and a replace string and replaces all occurences. query-replace-string Same as replace-string, but asks before replacing each occurence. incremental-search Searches the text for a string. String can be entered incremental. Deleting characters invokes a jump to the position, where the char- acter was added to the search-string. Adding a character tries to find the string. Aborting this command jumps to the calling- position. O_RETURN ends the search. O_UP, O_LEFT and O_FIND_REVERSE switch the searchdirection to backwards and search the string. O_DOWN, O_RIGHT and O_FIND switch the searchdirection to forward and search the string. incremental-reverse Same as ``incremental-search'', but it starts with searchdirection backwards. _4._5. _F_i_l_e_s read-file, O_OPEN_NEW_FILE Read another file for editing, saving the current one if required. next-file Read next file given in commandline, saving the current one if required. previous-file Read previous file given in commandline, saving the current one if required. save-file, O_SAVE_FILE saves the current file with the current name and language. write-file Prompts for a filename and `listing-mode'. The text is written to a new file with the current language. If `listing-mode' is set, the generated file is modified in the following way: the `language-definition-line' is removed in `begin-fold'-comments `{{{' are removed the `end-fold'-comments are removed July 23, 1991 - 15 - While using the language `Tds' it is impossible to set `listing- mode', because the the generated files have an incompatible struc- ture. insert-file, O_INSERT_FILE Insert File. Prompts for a filename, and imports this file into the file being edited at the current position. filter-buffer Filters the current text. Origami prompts for the name of a filter. The current text is saved and piped through this filter. Origami tries to move the cursor to the line where the cursor stood before executing this command. Environment variables ORIFILE, ORILINE and ORIWORD are set to current filename, textline and word. pipe-from-command Prompts for a command. This will be executed and its standard out- put is inserted in the text at current position. Environment vari- ables ORIFILE, ORILINE and ORIWORD are set to current filename, textline and word. pipe-to-command Prompts for a command. The current file will be piped to this com- mand as standard input. Environment variables ORIFILE, ORILINE and ORIWORD are set to current filename, textline and word. _4._6. _M_a_c_r_o_s define-macro, O_DEFINE_MACRO Records all keys into the keyboard macro buffer until define-macro is pressed again. Calling fix-macros is allowed during define- macro. execute-macro, O_EXECUTE_MACRO Call keyboard macro. execute-macro-??, O_CALL_FIX_?? (1<=??<=64) execute the fix-macro with number ??. These macrobuffers are also used from (defmacro ... ) in keybind, so that using these operation has the same effect as calling the keysequence from macro!. Buffers not used from keybind are empty. O_DEFINE_FIX Asks for the number of the fix macro buffer. The contents of the keyboard macro buffer is copied to this fix macro buffer. Using (deffun .. ) in keybind makes it impossible to overwrite the fix July 23, 1991 - 16 - buffer. _4._7. _S_h_e_l_l _c_o_m_m_a_n_d_s i-shell, O_SHELL Creates a shell. Exiting from this shell will return to Origami. Environment variables ORIFILE, ORILINE and ORIWORD are set to current filename, textline and word. shell-command Prompts for a command and starts a shell which executes it. Environment variables ORIFILE, ORILINE and ORIWORD are set to current filename, textline and word. suspend-origami If your system has job control, origami will be stopped and the cal- ling shell is reactivated. _4._8. _A_r_g_u_m_e_n_t_s Like in Emacs, you can repeat each command by using an numerical argument. The first digit is given by set-argument-. These functions read more digits of the argument until you type a non- digit. This non-digit may be a key sequence bound to a command or just a single character. It will be executed times. Pressing the abort-key will abort the repeated execution. These commands can not be used in macros. If you are defining a keyboard-macro, the repeated Operation is stored times in the buffer. set-argument-0 ... set-argument-9 _4._9. _S_p_e_c_i_a_l _f_u_n_c_t_i_o_n_s quote-character, O_QUOTE The next character typed in will be returned to the editor ignoring all keysequences starting with it. redraw-display, O_REFRESH Refresh and center screen. This is useful after getting things like ``Message from ...''. If you are working with a window environment which does not send a window-changed signal, you may use this com- mand after resizing a window. help, O_HELP Displays the helpfile $HOME/.origamihelp. Since there is no default file for this function, you can create your own helpfile. It may be useful for new and very complicated macros or other things you July 23, 1991 - 17 - always forget. describe-bindings Displays the keybinding file $HOME/.origamibind created by the key- bind compiler. If you are using multiple keyboards, origami will only display the entries concerning the current keytab. set-language, O_LANGUAGE Allows you to select the language for which the code is to be saved - ie the format in which folds are to be saved. If you choose `User', origami prompts for the begin- and end-commentstring used for hiding the foldcomments. Each string can be up to three charac- ters in length. describe-fold, O_FOLD_INFO Returns information on the fold depth, position and indentation of the current line, plus information about any fold the cursor is on. add-mode-view Sets view-only mode. delete-mode-view Sets edit mode. add-mode-overwrite Sets overwrite mode. Text input will overwrite other text. delete-mode-overwrite Sets insert mode. Text input will be inserted. add-mode-echo Incomplete keysequences are displayed under the statusline. delete-mode-echo Do not show unfinished keysequences. add-mode-auto-save Prompts for the auto-save duration. Origami will save your files periodically in auto-save mode. Default time is 8 minutes. delete-mode-auto-save auto-save is switched of. July 23, 1991 - 18 - set-user-mode Prompts for a string, which is displayed as additional mode in the statusline. Doing this again will overwrite the string. reset-user-mode No `user-mode'-string is displayed. O_PIPE_KBD Prompts for a command. This command will be executed and its stan- dardoutput will be read as keyboardinput for origami. Using O_PIPE_KBD while reading from a file instead of the keyboard will close all pipes! Environment variables ORIFILE, ORILINE and ORIWORD are set to current filename, textline and word. The general-abort- key stops the reading from a pipe. NOP No operation. This command can be used to disable keyboardinputs explicitly. abort Aborts any operation. There are several commands which can be aborted by this key. This operation can only be bound to a _s_i_n_g_l_e key. This key even stops a running macro, which may be useful if it contains an endless loop. If you are anxious of Origami doing some- thing wrong, this key brings you back to a safe state. _4._1_0. _H_o_w _t_o _g_e_t _o_u_t quick-exit, O_FINISH If needed exit entered folds, save the file and exit from Origami. exit-origami, O_QUIT If your file was changed since last save, Origami asks you if you want to leave anyway. _5. _P_r_o_g_r_a_m_m_i_n_g _i_n _O_C_L This chapter describes OCL (Origami control language) and gives some examples to show how powerful it is. OCL is a programming language offering capabilities to use conditional statements, subroutines, loops, variables and recursion. The keybind program compiles human readable OCL source code to a binary which will be interpreted by Origami. The functions described in the chapter explaining keybind- ings are very simple OCL statements. July 23, 1991 - 19 - _5._1. _O_C_L _s_y_n_t_a_x _a_n_d _s_e_m_a_n_t_i_c This sections describes all other OCL elements. It is assumed that you are familiar with other programming languages. You will find examples in a later section. _5._1._1. _O_t_h_e_r _m_a_r_k_s _f_o_r _f_o_l_d_s (defmark ( )) This option puts data in the rcfile, so that origami can switch to other marks for folds if it is invoked with commandline option `-mname'. The format for is: ( ) where is a ``"x'' definition like in (keybind ... ). The meanings of ... are: begin of fold, standard is `{{{' closed fold, standard is `...' name of filed/attached fold, standard is `:::' end of fold, standard is `}}}' _5._1._2. _S_u_b_r_o_u_t_i_n_e_s _a_n_d _m_a_c_r_o_s (defmac ( ... ) ) The Origami operations defined in ( ... ) are further- more reproducable as too, so you can use them to define other macros. Remark that these are really macros, they are only copied to the calling macrodefinition. Inside of ( ... ) you are allowed to use . The effect is, that ( ... ) is executed and afterwards the following statements are executed. (deffun ( ... ) ) The operations in ( ... ) are written to the .origamirc- file so that origami can initialize a fix-macro-buffer. Recursion is allowed. You can use in the following OCL-text as subroutine-calls or for keybinds. You cannot redefine the fix- macro-buffer. (initfun ( ... ) ) Same as above. But the macro can be redefined with ``O_DEFINE_FIX''. Using the commands `defmac' and `initmac' uses the fix-macro-buffers 64,63, etc. (forward ) is declared as a name for a macro defined with ``initfun'' or ``deffun''. can be used from now on as normal macro-call. July 23, 1991 - 20 - The definition with ``(deffun ... '' can be put somewhere in the following script. (automacro ) If Origami is invoked using the ``-A'' flag, the macro named is called every time you are exiting a filed fold, entering it or opening a new file. Warning: Using ``O_DEFINE_FIX x'' has no effect on macros defined with ``initfun'' or ``defmac'' when calling them by their name. If you want to use such an effect you must use ``O_CALL_FIX x''. _5._1._3. _C_o_n_t_r_o_l _s_t_r_u_c_t_u_r_e_s A can be one of the following control structures or functions: while ( ... ) Prechecked loop, the macro is repeated while the condition is true. do ( ... ) while Postchecked loop, the macro is repeated until the condition is false. if ( ... ) fi if ( ... ) else ( ... ) fi Conditional statement. If condition is true, the first macro is executed. If condition is false, the second macro, if any, is exe- cuted. case ( ( ... )) ... esac case ( ( ... )) ... default ( ... ) esac Conditional statement. The block of statements following the first conditional expression evaluating to TRUE is executed. If no condi- tion is true, the given default-statements are executed. repeat ( ... ) ( ... ) is repeated times. ATTENTION: The tokens are stored times!. This cannot be done in another way, because origami knows no local variables!. If you want to repeat big macros, think about an implementation with counters. prompt Displays below the statusline. can be: July 23, 1991 - 21 - ( ... ) where can be: counter Origami displays the ``prompt'' and waits till you type a ``O_RETURN'' on your keyboard. exit The macroexecution is aborted. Origami waits for keyboardinput. message-exit Same as exit. is displayed under the statusline. return-from-macro The currently executed macro ends and the caller (keyboard or macro) continues again. local ( ... ) ( ...) The values of the variables ... are saved during the execu- tion of `` ...''. After the execution of the ``local''- statement all saved variables are reset to their original values. ATTENTION: `` ...'' is executed as a subroutine, so using ``return-from-macro'' inside `` ...'' will only leave `` ...'', and not the current macro. All Origami commands you can use from keyboard can be used by their names. Normal text can be used. The syntax is: "text where text can be a any string not containing: " ) " for ") for ) "" for " Warning: if you use origami to edit a OCL-file: " should not be the last statement of a line, because origami deletes all spaces at end of line. If you put a comment after the " command you have no problems. July 23, 1991 - 22 - _5._1._4. _V_a_r_i_a_b_l_e_s OCL allows to use variables. OCL variables are global integer vari- ables. They are declared by using them. They are initialized to zero when Origami starts up. The following functions deal with variables and can be used in the same way like the above mentioned statements: set-counter The counter-variable is set to the value of . prompt-counter Prompts below the statusline and reads the new value for from keyboard. Input ``y'' sets it to 1, ``n'' sets it to 0. All other inputs have to be decimals or a simple O_RETURN. is explained in section ``Control structures''. read-repeat The counter-variable takes its value of the ``repeat- argument-counter''. This counter is set to 0, so that the macro- call is not repeated. The value of ``repeat-macro-counter'' is the number of remaining loops when using ``set-argument-x'', otherwise 0. add-counter The counter-variable is set to +. sum-counter The counter-variable is set to +. inv-counter The counter-variable is set to -. goto Move the cursor on x-position . 1 is the first displayed character. If you enter a indented fold, position 1 is not the first character on that line. goto-counter Same as above, except that the position is the value of variable . store-pos The x-position of the cursor is stored in the variable . July 23, 1991 - 23 - goto-line-counter Like O_GOTO_LINE. The linenumber is the value of variable . store-line The current line-number is stored in the variable . counter The current value of is returned as ASCII-text. _5._1._5. _B_o_o_l_e_a_n _e_x_p_r_e_s_s_i_o_n_s The above mentioned boolean expressions can be: not() The value of is inverted. and(,) is true, if both 's are true. or(,) is true, if one of the 's is true. pre ( ... ) The sequence of statements will be executed before the evaluation of . test-file-changed is true, if the current file has been changed. test-filed is true if the current line is a file-folded-line. test-fold-line is true if the current line is a closed-fold-line. test-begin-fold is true if the current line is the {{{ line of a open fold. test-end-fold is true if the current line is the }}} line of a open fold July 23, 1991 - 24 - test-text is true if the current line is a normal text-line. test-top is true if the current line is the top of the entered fold. test-bottom is true if the current line is the bottom of the entered fold. test-char "x is true if the character under the cursor is equal to x. test-language "x is true if x is the language used by ``set-language''. counter-0 is true if the variable is 0. counter>0 is true if the variable is greater than 0. test-begin-line is true if the cursor stands on or before the first non-space- character of the current line. test-end-line is true if the cursor stand behind the last non-space-character of the current line. test-behind-counter is true if the position in line is after the value of the counter- variable. OCL uses short-circuit evaluation for ``and'' and ``or''. Boolean expressions can be used everywhere in the code. When ``Origami'' is prompting for information (for example, if a existing file should be overwriten during O_FILE_FOLD), you can only use ``and'', ``or'', ``not'' and the following basic-expressions: July 23, 1991 - 25 - test-file-changed test-language test-text test-begin-fold test-fold-line test-end-fold test-filed test-counter-0 test-counter>0 _5._1._6. _M_u_l_t_i_p_l_e _k_e_y_b_o_a_r_d_m_o_d_e_s To create more complex keybindings (for example a ``vi''-emulation with modes), OCL offers the possibility to use up to four different keyboard-translation-tables. To do this, you must declare the used keytabs with: (defmodes ... ) where is a normal string. This command has two effects: j.J Keybind initializes a keytable for each . j.J The macros are defined and can be used within other macrodefinitions to switch to a certain keytab. They are not stores in fixmacrobuffers, but you can use them for your one macrodefinitions. The first mentioned mode is active when starting origami. The definition of a declared keyboard can be done with: (mode (keybind ... ) ... ) All given bindings are put into the keytable for . ``(keybind abort ... )'' must be declared outside a ``(mode ... )''- statement, which results in the fact that you can only have one abort-key for all modes. If using multiple keyboard modes, no other ``(keybind ... )''-statement is allowed outside ``(mode ... )''- statements. _5._1._7. _H_a_n_d_l_i_n_g _o_f _f_i_l_e_d-_f_o_l_d_s Using language ``NONE'', keybind will automatically include the con- tents of filed-folds when reading the source-file. Normally multi- ple includes of the same file won't work , because redefining macros isn't allowed. To build a clean macro-library, you can use: nodup The current file will only be read once even if you have another filed-fold entry for this file. This command makes it possible to have macro-libraries like: July 23, 1991 - 26 - file1: : ...F helps : file2: : ...F helps : keyboard: : ...F file1 ...F file2 : _5._2. _O_C_L _e_x_a_m_p_l_e_s This section explains some useful OCL applications. They are useful for understanding OCL. Perhaps you missed some functions while reading the previous chapters. Some of them are written in OCL and you will find them here. It is assumed that you are familiar with Origami before you start writing in OCL. _5._2._1. _A _f_i_r_s_t _e_x_a_m_p_l_e The first OCL example does not use any control structures. It defines a little macro named byebye. You should play a little bit with such macros for understanding how to compile them and for get- ting some syntax errors. ; this is an example for a macro-definition: (deffun byebye ( O_BOT_OF_FOLD O_START_OF_LINE O_RETURN O_UP "end " "of " "text )) (keybind byebye (M-"x "bye)) byebye creates a new line containing `end of text' at the end of the entered fold. _5._2._2. _S_h_e_l_l _v_e_r_s_i_o_n _c_o_n_t_r_o_l Two more little macros deal with SVC. Note that the check-out macro is only for personal use of SVC. If you are working in a group, someone else may have edited the file, which will not change your own read-only copy. The advantage is that you can visit a file and July 23, 1991 - 27 - decide if you want to change it. (deffun check-out ( delete-mode-view shell-command "co " "-l " "$ORIFILE )) (deffun check-in ( save-file add-mode-view shell-command "ci " "-u " "$ORIFILE )) _5._2._3. _M_T_o_o_l-_v_e_r_s_i_o_n _o_f _O__T_O_P__O_F__F_O_L_D This a macro-version of the command O_TOP_OF_FOLD as it is used in the mtool-system. The cursor moves to the begin of the currently opened fold. ; example for a more complex macro (deffun mtool-top ( if test-end-fold (O_UP) fi while and(not(test-begin-fold),not(test-top)) ( if test-end-fold (mtool-top) fi O_UP ) ) ) While the cursor is not being located on top of a fold (entered or opened) the cursor is moved up. If the macro finds the end-of-fold line from another opened fold, this fold is skipped by a recursive call of mtool-top. _5._2._4. _F_i_l_l _p_a_r_a_g_r_a_p_h The following example is an advanced macro. It is too long for printing it here, but it is included in the file fill-paragraph. fill-paragraph fills all lines from cursor position to the next line with a blank or a dot in the first column. An end of a fold stops filling too. The first column of a line is here the first character in currently entered fold, not opened fold! Filling a line means to add words from the next line if it is too short or to put words to the next line if it is too long. The default right margin is set to column 72. If there are unfillable lines, fill- paragraph stops filling and complains. The filling can be done in the following 3 ways: roff-mode (switched on when origami starts) All ``. '' are expanded to ``. ''. July 23, 1991 - 28 - block-mode All `` '' are expanded to `` '', till the line reaches the fill-margin. ragged-mode All `` '' are replaced bye `` ''. The macro inv-blank-handle switches between these modes. The macro set-fill-column allows to change to right margin. To do so, you can either use a numeric argument or put the cursor to the position of the new right margin or put it to the left and wait for Origami asking you about the new column width. _5._2._5. _G_o_t_o _m_a_t_c_h_i_n_g _f_e_n_c_e If you are writing programs, you often want to know which closing paren in a complicated expression fits to another opening paren. goto-matching-fence performs this function. It uses the character under the cursor to determine if you are looking for a paren, a bracket or a { and if you want to jump to the opening or the closing one. If the cursor stands somewhere in usual text, nothing will happen. Hereafter the macro searches the matching fence. If it can't find it, it will jump back to your old position. If neces- sary, this macro opens and closes folds. Do not worry if it does not seem to stop searching. If your text is very long and there is no fitting fence, you will be amazed how many folds you are using and how fast they can be opened and closed, but usually goto- matching-fence goes back to your old position. _5._2._6. _T_h_e _t_o_w_e_r_s _o_f _h_a_n_o_i This is a funny macro to demonstrate the power of OCL. You should type a string of a few characters without blanks, then start this macro and have fun. Warning: If you type more than about eight to ten characters, the game will require a long time. I am sure that you will invent more useful OCL macros. If you wrote a really new and good one, please post it to the USENET news- group comp.editors. _6. _M_i_s_c_e_l_l_a_n_o_u_s _t_h_i_n_g_s Sometimes, it is useful to know if a document contains ``dangerous'' strings for Origami. The following simple shell script searches these strings. fgrep '{{{' fgrep '}}}' fgrep ':::' July 23, 1991 - 29 - _7. _C_o_p_y_r_i_g_h_t _a_p_p_o_i_n_t_m_e_n_t_s This chapter wasn't included in earlier versions, but a discussion on USENET convinced me to write it. Please read it careful. Each part of this software can and must be copied free. If you copy binaries, you must not prevent people from copying sources, too. You must not remove my name from this program. If you want to use parts of it for your own purposes, point out what is your code and what is mine. If this software is used on a machine, no one may forbid other people to use it on the same machine. (A little bit uncommon. I hope it prevents some braindamaged teaching methods I saw here at the RWTH in Aachen recently. No more comments at this place.) If you have problems with this restriction then send me mail, please. I will try to get a clearance. No part of this software may be used for military purposes. I will make no execptions for this point. If someone want to use software from this package for commer- cial purposes, he needs a written non-exclusive license. There are no remarks in the other files of this package about copyright and these things, because program code and comments about it are two different things, but the above conditions are valid for the whole package! _8. _A_c_k_n_o_w_l_e_d_g_e_m_e_n_t_s Most of this manual was written by me, but the original was written by someone else, who didn't leave his name in it. The concept of the folding editor was originally implemented as part of the Tran- sputer development system at INMOS Ltd., Bristol, UK. The editor was a part of the TDS D700, and was written in Occam. It first ran on a 68000 based Sage/Stride development system, and later was Tran- sputer resident on the PC development system. Origami was rewritten from scratch in Turbo Pascal by Martin Green while at Ferranti Ltd, Cheadle Heath, Stockport, England, and used the same key mappings and editor functions as the TDS editor. It was then converted from Turbo Pascal by p2c and ported by Charlie Lawrence, while at Eastman Kodak Co. He added lex/yacc based keyfiles, and did the considerable work needed to get it run- ning in C. I fixed some bugs in memory managment and otherwhere, ported it to MINIX, changed its user interface to look more Emacs-like and added new features. A friend of mine, Wolfgang Stumvoll, wrote the OCL code and the keybind compiler. He also made beta tests of all my new versions by using them for his daily work, which helped a lot to find existing and new bugs. Last but not least, he wrote the OCL July 23, 1991 - 30 - fill-paragraph, goto-matching-fence and towers-of-hanoi macros. Both of us made a general code clean-up, which was highly overdue. Michael Schwingen ported Origami to Atari TOS and fixed a few minor bugs. I maintain the whole Origami source code, which means that I will answer or forward mail concerning Origami, decide if and how extensions should be made, give advices for people who are porting it, post new versions and update the documentation. July 23, 1991 @