u31b3hs@cip-s02.informatik.rwth-aachen.de (Michael Haardt) (04/22/91)
Hello world,
at first I want to tell all beta-testers of Origami and MROFF something
very important: I forgot to put a few things to my archive in Cologne.
Please ftp the following files if you got the version from friday:
Server: ftp.thp.uni-koeln.de [134.95.64.1]
Path : minix/beta-test
Files : mroff.tar.Z, hfont.tar.Z, mmac.tar.Z
Sorry for this, I promise not to make it a habit.
AST and a few other people from comp.os.minix sent me mail because they
never heard of `folding editors' before. The principles of folding
editors are described in the documentation, but not all people want to
ftp origami, unpack it, format the documentation etc. Therefore, I
picked the important parts/folds from the documentation and concatenated
them to this document. This document is in nroff -ms format (even MINIX
nroff was capable to format it at home).
A short summary about Origami: A powerful (like emacs: a million
commands and no insert mode) but very small editor, a macro language for
complicated editor tasks and a new concept. Nothing you want to use
under bad circumstances (bad terminal links, 1 bit/sec etc), but a nice
editor for usual work.
Namaskaar
Michael Haardt
---------- snip, snip, snip ------- cut, cut, cut --------------
.\"{{{ Introduction
.NH 1
Introduction
.\"{{{ Origami
.NH 2
Origami
.LP
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.
.PP
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. The structuring of the code is obvious
from the screen display (if Origami is sensibly used!), although no
actual code may be visible.
.PP
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.
.\"}}}
.\"{{{ The Folding Editor
.NH 2
The Folding Editor
.LP
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.
.PP
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
containing 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.
.PP
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.
.\"}}}
.\"{{{ Examples of Origami folding
.NH 2
Examples of Origami Folding
.LP
As an example, a Pascal file might look like this at
the top level (eg immediately after starting Origami):
.DS L
program test;
\&... CONSTs
\&... TYPEs
\&... VARs
\&... procedures
\&... main body of code
.DE
OPENing the VARs fold might lead to the following display:
.DS L
program test;
\&... CONSTs
\&... TYPEs
{\&{\&{ VARs
VAR i : integer;
x : real;
}\&}\&}
\&... procedures
\&... main body of code
.DE
ENTERing the procedures fold might give:
.DS L
{\&{\&{ procedures
\&... statistical procedures
\&... string handling procedures
\&... procedure user_input
}\&}\&}
.DE
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:
.DS L
{\&{\&{ 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;
}\&}\&}
.DE
.\"}}}
.\"}}}
.sp
[...]
.sp
.\"{{{ Processing
.NH 2
Processing Origami Files
.LP
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 Origami 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 \(em not allowed
in some languages.
.PP
Origami knows the languages None, Occam, Pascal, C, Lisp, Roff, Fortran,
User and Tds. You can specify your own comment strings using language
User. Tds allows to edit files generated by Tds and MultiTool without
converting them.
.\"}}}
.sp
[...]
.sp
.\"{{{ mtool-top
.NH 3
MTool-version of O_TOP_OF_FOLD
.LP
This a macro-version of the command O_TOP_OF_FOLD as its used in the
mtool-system. The cursor moves to the begin of the currently opened
fold.
.DS
; example for a more complex macro
(deffun mtool-top (
while and(not(test-begin-fold),not(test-top))
(
O_UP
if test-end-fold
(
mtool-top
O_UP
) fi
)
))
.DE
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.
.\"}}}
.sp
[...]
.sp
.\"{{{ fill-paragraph
.NH 3
Fill paragraph
.LP
The following example is an advanced macro. It is too long for printing
it here, but it is included in the file fill-paragraph.
.PP
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. First column of a line is here the first character in
currently entered fold, not opended 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.
.PP
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.
.\"}}}
.sp
[...]
.sp
.\"{{{ goto-matching-fence
.NH 3
Goto matching fence
.LP
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 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 neccessary, 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 not 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.
.\"}}}