home *** CD-ROM | disk | FTP | other *** search
/ The C Users' Group Library 1994 August / wc-cdrom-cusersgrouplibrary-1994-08.iso / vol_300 / 331_01 / read.me < prev    next >
Text File  |  1990-06-15  |  25KB  |  439 lines

  1. .ce
  2.                              The SE Editor
  3.  
  4. .fi
  5. .rm 76
  6.  
  7. This file announces the release of yet another of the derivatives of the 'e'
  8. editor.  The highlights of this version are:
  9.  
  10. 1) Utilizes up to 500 kb of RAM for text storage, while functioning with as
  11. little a 6kb of allocatable memory. 2) The efficiency of the virtual disc
  12. system has been doubled by adding a stale page directory.  The speed of disc
  13. reads has been improved. 3) An embedded runoff function will reformat
  14. internal text per dot commands. 4) A text push stack has been added for
  15. pushing and popping lines. 5) The undo capability has been extended to
  16. include redo. 6) The program supports free cursor movement. 7) Numerous
  17. enhancements to the command and display structure have been made, while
  18. retaining Wordstar [1] compatibility where feasible and reasonable.  Many of
  19. the enhancements are cosmetic, not affecting the command structure, but
  20. improving the visibility or convenience of use.
  21.  
  22. The starting point for this system was the GED version, CUG 199.  The
  23. contributors to that version were G.  Nigel Gilbert, James W.  Haefner, and
  24. Mel Tearle.  Several small errors have been corrected.  The new version
  25. compiles under Microsoft 4.00.  This compiler allows selective use of far
  26. pointers, opening up the possibilities of the large memory model without its
  27. usual inefficiency.  Some effort has been made to otherwise maintain
  28. compatibility with the DeSmet starting point, but the thoroughness of the
  29. compatibility has not been tested.
  30.  
  31. The architecture remains that of the earlier versions.  It is a good
  32. architecture, providing a solid foundation for further enhancements and
  33. additions.  Due to the ancestry of the program, the architecture is oriented
  34. to the needs of a slow remote terminal.  In the interest of portability,
  35. that design philosophy has been retained, even though some shortcuts could
  36. have been taken with the direct access to the video RAM in the PC's.  The
  37. shortcuts would compromise the portability of the program.
  38.  
  39. There are preprocessor directives in the header file which can be changed to
  40. remove all occurrences of the near and far keywords, making the code
  41. compatible with compilers which do not support mixed memory models.  Most
  42. users will not find the capabilities of the program running under the small
  43. memory model overly restrictive.  The virtual memory system is effective in
  44. masking the shortcomings of a small RAM.
  45.  
  46. A tidying up operation has been performed, including the addition of many
  47. comments.  The new code, now in its third compiler port, should be mostly
  48. vanilla.  An attempt has been made to further segregate those functions
  49. which are system dependent (IBM PC, MSDOS) to simplify rework for a port to
  50. a different system.  The strategy in porting the system to an entirely
  51. different environment is to replace the system interface routines
  52. altogether.
  53.  
  54. The program is configured for editing a 2.4 megabyte english dictionary
  55. consisting of 10000 lines of 253 characters each.  The maximum file size
  56. will be less for 80-character lines.  The maximum number of lines in a file
  57. is 16383.
  58.  
  59. The line limit may be less for small memory systems, but remains adequate
  60. for most work in any plausible system. 1000 line files can be edited with
  61. only 8 kb of allocatable RAM.  A line pointer array is kept in RAM, so all
  62. line jumps are instantaneous if the text is in RAM, or just the disc access
  63. time (without searching) if all the document won't fit in RAM.  The virtual
  64. memory system keeps the most recently used pages in RAM, as they are the
  65. most likely to be used or viewed again.  Global string searches have little
  66. effect on the established page priorities.  They normally search all pages
  67. and are given special consideration so that they do not upset the virtual
  68. memory priorities established by earlier editing and display functions.
  69.  
  70. Earlier versions unconditionally wrote a page back to disc if the RAM slot
  71. was needed for another use.  This version does not do a disc write if the
  72. virtual memory page is unchanged since being rolled in from disc.  In a
  73. further refinement, the line pointer array and text pages are allocated
  74. beginning from opposite ends of memory, so that they do not collide until
  75. RAM is exhausted.  Collision was immediate in the earlier versions,
  76. resulting in unnecessary disc thrashing during the initial read.  If enough
  77. RAM is available the new version will not create a temporary disc file at
  78. all.
  79.  
  80. Tree directories are supported.  An error in earlier versions which made
  81. filespecs of the form ..\filespec unusable has been corrected.  The
  82. temporary disc file normally goes in the default directory of the default
  83. drive.  The -D invocation option can be used to place the temporary file on
  84. any drive.  In browsing through the files on floppy discs from a hard disc
  85. system, nothing is written to the floppy disc unless directed there from the
  86. keyboard.  Archived files can be studied with little risk of accidental
  87. modification.
  88.  
  89. The program updates the screen before the data base, making it seem faster
  90. than it is in some cases.  In the case of line deletions or insertions, all
  91. the line pointer array beyond the modified point is moved.  The processing
  92. delay is seen if a second key is entered during the move.  The delay becomes
  93. noticeable and objectionable at about 5000 lines on a 5 MHz PC.  The delay
  94. is not objectionable (and rarely seen) with 16000 line documents on an 80286
  95. or faster system.
  96.  
  97. On a 5 MHz PC the primary file is read at the rate of 5200 characters per
  98. second from fixed disc; at 3000 characters per second from floppies.  The
  99. string search operation proceeds at 30,000 characters per second if the
  100. material is in RAM.  The search rate exceeds 200,000 characters per second
  101. on more recent systems.
  102.  
  103. Learning to use any word processor effectively represents a significant
  104. investment in time.  For that reason I have tried to adopt or retain the
  105. Wordstar keyboard layout for the frequent and habitual keystrokes.  But in
  106. the more complex and less frequent functions, and when there is is ample
  107. visual prompting or feedback, significant deviations have been made.
  108.  
  109. Some editing programs trap the cursor within the portion of the screen
  110. containing text for reasons which are surely without merit.  The package has
  111. been modified to allow free cursor movement.  The horizontal domain of the
  112. cursor lies between columns 1 and 255.  The ^D, right arrow, and ^] (end of
  113. line) cursor positioning commands will move the cursor past the right end of
  114. the line.  Doing so creates temporary spaces at the end of the line, but
  115. they are removed before the line is stored.  Editing is performed as though
  116. each line had spaces all the way to the right.  Free cursor movement is a
  117. great convenience in editing C code because the cursor will stay at a fixed
  118. indentation level when moved vertically.
  119.  
  120. The -S option restores the earlier mode.  In this mode the cursor is trapped
  121. within those regions already containing text (or trailing spaces).  In this
  122. mode it is unnecessary to strip trailing blanks before lines are stored, and
  123. they are not.  That is what the mode used for.  But otherwise, the first
  124. time a file passes through SE without the -S option it may shrink in size
  125. without any editing activity.  The thing lost is trailing whitespace.
  126.  
  127. The GED version had a full undo capability, but I quickly discovered that
  128. after undoing more than two lines I had always forgotten what I had changed
  129. and why.  The changes I saw occurring on the screen in time reversal didn't
  130. make any sense.  To overcome that problem I modified the undo algorithm to
  131. be reversible and with that there is redo.  The same algorithm and the same
  132. code is used for both.  The complete algorithm is surprisingly compact.  By
  133. moving back and forth along the edit trail it is usually possible to
  134. recognize the correct restoration point many lines back.  Undo is nice, but
  135. it is redo that makes it work.
  136.  
  137. As each line is undone or redone it appears in reverse field on the screen.
  138. The cursor follows the undone and redone lines about the document.  So long
  139. as the undo capacity of the program is not exceeded (it runs 50 to 100
  140. lines, depending on the activity), the restored program is guaranteed to be
  141. identical with the original.  There are no restrictions on the complexity of
  142. the undo steps, and no restrictions on changing changed lines.
  143.  
  144. When the undo mode is entered with ^- (ctrl-minus), the program
  145. automatically locks out all editing commands.  That is necessary because as
  146. soon as any change is made the redo capability from that point forward is
  147. lost.  When in the undo/redo mode, which is prompted, the + key (not
  148. ctrl-plus) becomes the redo key.  The lockout makes it safe to browse
  149. backward and forward on the edit trail.  The global search and replace
  150. operations can be undone.  The insertion of disc file with ^KR can also be
  151. undone.  All editing operations can be undone.
  152.  
  153. Although the stack operations have some restrictions, they are nevertheless
  154. a useful and heavily used operation.  They provide an easy way of moving a
  155. line of code, of transposing lines, and of duplicating lines.  Pushing
  156. several lines then popping them elsewhere is a convenient way to move a
  157. small block.
  158.  
  159. The text stack shares a data base with the undo function, so the undo and
  160. pop operations have some conflict.  Pops can be undone, but if the editing
  161. operation which did the push is undone then the associated pop will find the
  162. stack empty.  The ^O and ^P stack operations pop the lines pushed with ^Y.
  163. ^O pops a copy of the line; ^P is the conventional pop.  The cursor must be
  164. in column 1 for a ^Y push to occur.  The stack will hold 100 lines.
  165.  
  166. A few editing operations other than ^Y (such as line concatenation) affect
  167. the stack also and can result in unexpected items on the stack.  Don't do
  168. too much editing if items are to be popped from the stack.
  169.  
  170. The ^J linejump command has several prompted options.  It will jump to the
  171. line last changed.  That is a good way to return to the point of editing
  172. after browsing elsewhere.  It is also at times a good way of jogging the
  173. memory, even to the extent of determining if anything at all has been
  174. changed.
  175.  
  176. Up to three lines can be marked with the ^JS (set mark) option.  A
  177. subsequent ^JM (jump to mark) will return to that point.  If the cursor is
  178. already on a marked line, then a second ^JM moves it to the line marked
  179. before that one.  If a fourth line is marked then the oldest marked line
  180. becomes unmarked.  If the cursor is on the oldest marked line then it moves
  181. to the newest marked line.  A ^JJ will jump to the last jump.  The most
  182. common form is ^Jn, where n is a line number.  All jumps are instantaneous,
  183. regardless of the document size.  No searching is involved.  The marked
  184. lines are not modified; it is the line number which is stored.  The list of
  185. line numbers is automatically adjusted if lines are inserted or deleted
  186. before that point.
  187.  
  188. The other means of maneuvering about a large document is with the string
  189. search.  With a 30,000 to 200,000+ character per second search rate the
  190. technique becomes more attractive than when using the slower commercial
  191. packages.  The F3 and F4 keys can be used to rock back and forth between two
  192. widely separated occurrences of a word, making intercomparison of the two
  193. areas easy.  Search keys are remembered until changed, regardless of other
  194. activities.  The Wordstar ^QF,^QA, and ^L commands have also been retained
  195. for compatibility.
  196.  
  197. All search and search/replace operations wrap at beginning and end of file.
  198. In a forward search the first possible match begins at the character
  199. immediately to the right of the cursor.  The last possible match is at the
  200. initial cursor position, but only after the search as proceeded to the last
  201. line, restarted at the first line, and finally returning to the initial
  202. position.  Complementary rules apply to backward searches.
  203.  
  204. For moving a few pages from the current line the easiest way is with the ^R
  205. and ^C keys, which are the same as the PgUp and PgDn dedicated keys.  With
  206. dense text the screen refresh time is 350 milliseconds on a 5 MHz PC.  This
  207. time is near the minimum achievable with the hardware.  The program avoids a
  208. complete screen rewrite whenever possible by using the faster scroll
  209. function.
  210.  
  211. The most common use of the F6 "center window" command is when a few of the
  212. displayed lines extend offscreen to the right.  If the cursor is already
  213. near the right of the screen, and if the line ends are not too far offscreen
  214. to the right, it will move the window right just far enough to view the last
  215. portion of the lines.
  216.  
  217. A -p option has been added to allow the importation of Wordstar document
  218. mode files.  This option is probably useful with word processors from some
  219. other manufacturers also.  The only function performed by the -p option is
  220. to zero the high order bit of each ASCII character in the primary file as it
  221. is read.  Some editing will be required after the conversion, but the input
  222. is at least legible.  SE does not create any hidden control characters for
  223. the disc output.  The only format control function is the dot commands,
  224. which are edited like any other text.
  225.  
  226. SE will read and display something for any possible disc file format, even
  227. binary files.  The binary capability has no value, but the text in the files
  228. from any other word processor can at least be seen.  The read operation is
  229. terminated by an end of file character, however, and some packages do
  230. include binary or graphic data, which might contain an internal end of file
  231. byte.
  232.  
  233. SE is capable of producing files with ASCII codes in the range 0x80 to 0xFF.
  234. These codes, which include the graphic symbols, are entered by holding down
  235. the Alt key and entering the 3-digit decimal code on the numeric keypad (The
  236. translation is performed by BIOS, and works for all programs).  A method is
  237. also provided of entering codes 0 through 0x1F, although the use of the
  238. control codes in text is not encouraged.
  239.  
  240. Input files are automatically detabbed in this version.  The tab key is a
  241. cursor positioning command.  Its use does not alter the text.  Earlier
  242. versions of the program had the capability editing files with tabs, and of
  243. retaining the tabs.  The only advantage to that is that it saves disc space,
  244. while complicating the manual interaction.  A capability of entabbing the
  245. output file at the time it is written would be a useful enhancement, because
  246. it is a simple form of file compression for sparse data.
  247.  
  248. A consideration in the command changes has been that there should be only
  249. one program mode.  The problem with multiple modes is that, assuming
  250. independence, there are 2^n states to remember.  I am convinced by
  251. experience that I cannot handle more than n=0.  The natural language editing
  252. is performed in the same mode as the editing of computer programs.
  253.  
  254. Now it is true that the keyboard designers had in mind that the character
  255. replace mode should be the primary mode, so they provided an insert key for
  256. inserting characters.  That seems to make sense, but it really doesn't.  The
  257. prime mode is the insert mode, and the insert key is used to leave it.  Most
  258. will prefer it that way, but the rules are easily inverted if the other way
  259. is more familiar.
  260.  
  261. An attempt has been made to structure the error messages and prompts so that
  262. a new user will eventually be led into the nooks and crannies of the
  263. features, while at the same time not cluttering up the screen with all the
  264. possibilities at the top level.  The F1 help key shows the basic commands.
  265. A different help display is shown in the paragraphing mode.
  266.  
  267. The backspace key is a destructive backspace.  The left arrow and the ^S
  268. keys are for moving the cursor left.  The backspace key is for correcting
  269. typing mistakes.  The usage is not the same as that of Wordstar, but the
  270. destructive backspace is nearly a universal standard elsewhere.
  271.  
  272. The method chosen for paragraph reforming is familiar yet unusual.  A runoff
  273. program has been embedded in the program.  Its functions are conventional
  274. except that it operates directly on the memory image and, unless otherwise
  275. requested, leaves the dot commands in.  Thus it is the master file which is
  276. reformatted, after which editing of it can resume.  This technique provides
  277. a flexibility and power not readily achievable by other means.  It also has
  278. the advantage of not embedding hidden control characters in the text.  Both
  279. the command and the effect of the command can be seen at the same time.
  280.  
  281. The runoff function is used in more than one way.  First of all, if the
  282. master file is being reformed then the dot commands should be restricted to
  283. those which are reversible by automated means.  Those which are reversible
  284. are flagged in the help display for the ^QP reform function.  A function
  285. such as changing the right margin is reversible by simply changing the dot
  286. command argument back to its original value and reforming.  A function such
  287. as creating a header line with page number is not automatically reversible,
  288. because the command creates new lines which must be removed manually if they
  289. are not wanted.
  290.  
  291. So if the objective is to actually produce a hard copy, the full set of dot
  292. commands are used and the result written to a temporary print file with the
  293. ^KW command.  The F9 key is used to exit the program without changing the
  294. master file.  The same method is useful for seeing what the final will look
  295. like on paper, but without the need of actually making a hard copy.  The
  296. screen will become a direct image of the result.  The restricted set of dot
  297. commands reversibly tidy up the material for further editing.  They make the
  298. material easier to read, and easier to enter because the paragraphs can be
  299. ragged.  Dot command defaults are provided, so that simple paragraph
  300. reforming can be accomplished without the use of any dot commands.
  301.  
  302. The program does not distinguish between document files and non-document
  303. files.  Document files will usually contain dot commands, but that is not
  304. required.  It also makes no difference whether the right end of a line is
  305. terminated by a carriage return or by some other cursor positioning command.
  306. The program does not use carriage returns or line feeds internally.  All
  307. strings are internally null terminated, and no memory is retained of the
  308. method of line termination.  If the line looks terminated on the screen then
  309. that is the way that it is.
  310.  
  311.  
  312.  
  313. .ce
  314.                                 Future work
  315.  
  316. No spelling correction capability is bundled with the package, but that
  317. probably would not be a good idea anyway, as it would needlessly complicate
  318. the code maintenance problem.  See CUG 217 and 218 for spelling correction.
  319. Hyphenation is closely related to spelling correction, and is also not
  320. bundled with the editing function.
  321.  
  322. It is not clear at this point that it would be a good idea to build the
  323. quirks of the individual printer manufacturers into a general purpose
  324. editing program.  For printers of the complexity of the laser printers a
  325. fully developed runoff program is a major program in its own right.  The
  326. same is true of phototypesetting.  The output of SE is nevertheless usable
  327. for these purposes with a suitably rich set of dot commands and a
  328. post-processor.  To that end, SE ignores dot commands that it does not
  329. recognize.  Thus with a capability of true proportional spacing the screen
  330. image would not be quite the same as the printer output, but it would
  331. nevertheless be close enough to prevent most command and editing blunders.
  332.  
  333. Another feature which would be nice at some time in the future is a
  334. configuration disc file.  This file should be an ordinary text file so than
  335. an arcane configuration mode is not needed to change it.  It should contain
  336. all the invocation options and the keyboard translation table.  The
  337. possibility of finding any one keyboard layout to which everyone agrees is
  338. remote, so the file should contain a key translation table.
  339.  
  340. There is a need for new natural language commands.  A means of pushing and
  341. popping whole sentences without regard for line boundaries would be useful,
  342. for example.  There are not many convenient and portable keys left for the
  343. natural language functions.  A mode change which is good for one command
  344. only is one possible way of extending the command structure.  A separate
  345. program mode would not be a good way, because computer programs contain
  346. natural language comments.  I have found on other systems that the escape
  347. commands with one or two letter command name are not so inconvenient as it
  348. might seem.  Remember that a control key counts as perhaps 1.5 keystrokes
  349. rather than 1.  That is to be compared to the 2 or 3 keystrokes for an
  350. escape command.  The visible feedback provided by the command line also
  351. gives it an advantage for functions where the visibility is relevant.  The
  352. same feedback would be distracting when it is not relevant.  The ALT and ESC
  353. keys are available for the natural language extensions.
  354.  
  355. Another extension needed by the program is a true macro capability.  The
  356. stream editors from the Unix environment illustrate the power of the
  357. technique.  The utility of push stacks is well established as a method of
  358. implementing automatic procedures, suggesting that the text stack capability
  359. of the program be extended to include macros.  The first step would then be
  360. to expand the stack capability to include items of type word, type line, and
  361. type column.  The type word and type column items would displace
  362. horizontally when popped; the type line would displace vertically.  Any item
  363. which can be deleted as an entity is a candidate for a stack item.
  364.  
  365. The next essential element is a cursor trapping capability when in the macro
  366. mode.  The popped item would appear in reverses field with the cursor
  367. somewhere within it.  The macro-driven cursor positioning commands, mostly
  368. in the form of generalized string searches, would be limited to that region.
  369. A macro step would fail when the string is not found, causing the alternate
  370. macro path to be taken.  Two stacks are probably needed, with a simple way
  371. of toggling between them.  Problems as complex as alphabetizing a list and
  372. conditional block replacement based on elaborate rules can be accomplished
  373. with this technique.
  374.  
  375. In order that the macros be alterable in the same way as any text,
  376. equivalents of the control character commands would have to be provided in
  377. readable form so that the macro is composed of visible characters which can
  378. be edited without complication.
  379.  
  380.  
  381.  
  382.  
  383. .ce
  384.                               Getting started
  385.  
  386. The file keys.doc contains the operating instructions.  The program compiles
  387. under the Microsoft 4.00 compiler.  The batch proceedures use a \obj
  388. subdirectory to avoid cluttering the main directory.  The build.bat
  389. procedure will reconstruct all the object files (not included).  The one
  390. assembly language file is included in both source and object form for those
  391. without an assmebler.  The link edited and executable result is in se.exe
  392. (included).  Edit a program with the minimum command line SE FILESPEC.
  393.  
  394. The program has been used on systems ranging from a 5 Mhz PC clone to a 25
  395. MHz 80386.  It should run on most any system supporting DOS 2.0 or later.
  396. You will want to reconfigure the video parameters in ged.h for a color
  397. monitor, but the program is usable as-is on almost any system.  The timed
  398. delays are independent of CPU speed.  The program does make direct access to
  399. the video memory, but that usually does not cause compatibility problems.
  400. The 80386 may virtualize these direct accesses on the more advanced systems,
  401. but it still works.
  402.  
  403.  
  404.  
  405. .nf
  406. The main files are:
  407.  
  408. ged.h     header file
  409. se.c      top level
  410. edit.c    basic editing operations
  411. search.c  string search
  412. roff.c    paragraphing
  413. block.c   block operations
  414. ged1.c    disc directory, options
  415. hist.c    undo, push/pop
  416. paint.c   screen output
  417. ged10.c   disc library functions
  418. ged5.c    open and close files
  419. ged7.c    low level terminal i/o, help display
  420. store.c   store lines
  421. swap.c    virtual memory
  422. term.c    (terminal) low level screen and keyboard interface
  423.  
  424.  
  425.  
  426. Gary Osborn
  427. Electro Chemical Devices, inc
  428. 23665 Via Del Rio
  429. Yorba Linda CA 92686
  430.  
  431. June 1990
  432.  
  433.  
  434.  
  435. [1] WordStar is a trademark of Wordstar International, 33 San Pablo Ave, San
  436. Rafael, CA 94903.
  437.  
  438.  
  439.