xref: /xsrc/external/mit/xedit/dist/README

      Xedit is a simple text editor for X.

      Please check xedit(1) for  information about resources  and configurable
  options.

      The authors  file should  list the  original authors  of all  files, but
  unfortunately most  collaborators and  people that  changed portions  of the
  code is not listed.


      List of default keyboard commands.
  Uppercase letters means both, uppercase and lowercase.
  Lowercase letter usually means Shift key is not pressed.
  C-    Means Control key.
  M-    Means Meta key.
        Usually Alt key has the same effect.
  S-    Means Shift key.

  C-A   Move cursor to beginning of line.
  C-B or Left
        Move cursor backwards one character.
  C-C   Insert CUT_BUFFER0 selection at cursor position.
  C-D   Delete next character.
  C-E   Move cursor to end of line.
  C-F or Right
        Move cursor forwards one character.
  C-G   Keyboard reset.
        Use it to switch direction in the Undo stack, i.e. switch between
        Undo and Redo.
        It can also be used to stop the lisp interpreter if it is executing
        code.
  C-H   Deletes character before cursor.
  C-J   Adds a newline and indent.
        If the current buffer is the *scratch* buffer, it will work
        like C-X,C-E, but print the lisp output directly to the scratch
        buffer. Examples:
        (list 1 2 3) C-J will print (1 2 3) and move the cursor to
        the next line.
  C-K   Deletes text from cursor position to end of line.
  C-L   Redraw text window.
  C-M   Adds a newline.
  C-N or Down
        Move cursor to next line.
  C-O   Adds one newline at cursor position without moving cursor.
  C-P or Up
        Move cursor to previous line.
  C-R   Opens search dialog, searching backwards.
  C-S   Opens search dialog, searching forwards.
  C-T   Transpose characters.
  C-U   Starts multiply mode.
        Multiply mode means that most keyboard commands will be repeated
        by its parameter. After pressing C-U type a number, that can be
        negative. Examples:
        C-U 10 C-F  will move the cursor 10 characters forwards
        C-U -10 C-F will move the cursor 10 characters backwards
        If no number is specified, or if the number zero is specified,
        the default value is 4.
  C-V or PageDown
        Move cursor to next page.
  C-W   Kills current selection.
        C-W is also useful when there is no active selection, to return to
        the previous position the left mouse was clicked in the text window.
  C-Y   Inserts SECONDARY selection.
        This usually means text delete with commands other than by just
        pressing Backspace or Delete (that can be multiplied)
  C-Z   Scroll one line up.
  M-B or C-Left
        Move cursor backwards one word.
        C-Left only moves over alphabetic or numeric characters
  M-C   Capitalize word under cursor position, or next word.
  M-F or C-Right
        Move cursor forwards one word.
        C-Right only moves over alphabetic or numeric characters.
  M-I   Opens  a dialog prompting for a file name to be inserted at the
        cursor position.
        (This isn't very user friendly, this is a cavemen interface, you will
        love it, you will never use it).
  M-K   Kills text from cursor position to end of paragraph.
  M-L   Downcase word at cursor position or next word.
  M-Q   Format paragraph.
        Xedit interfaces Xaw code that allows several types of text
        formatting. To use it, you need to Select "Auto Fill" in the
        "Edit Menu" and select values for "Break Columns". After that,
        Select "Edit Menu"->"Justification" for the available options.
        Text typed will usually be automatically corrected, but if you
        need to change text in the middle of a previous line, use M-Q
        to reformat, and C-_ to undo if required.
        Examples of text:

                    This text with align
                    left and break
                    columns at 20 and
                    40.

                         This text with align
                              right and break
                            columns at 25 and
                            45. Remember that
                            Auto Fill must be
                         selected. And it may
                         be required to press
                          M-Q when going back
                             to edit previous
                                       lines.

                                         This text with align center
                                         and break columns at 40 and
                                        70. A good tip is to make sure
                                         there are empty lines before
                                        and after the aligned text, so
                                        that M-Q will not format more
                                             text than it should.

                 This text  with full  align,
               note that  it will  spread the
               words  to   fully   fill   the
               configured break  columns,  in
               this case 15 and 45. Also note
               that  it  doesn't  remove  any
               extra  indentation   from  the
               first  line.   This   may   be
               considered a  bug or  feature,
               but  it   doesn't  respect   2
               spaces after  an '.'  dot. And
               it doesn't align the last line
               of text.

  This text with Auto Fill disabled. When Auto  Fill is disabled, tabs are
usually preserved, like this,		and			this. But it
will basically format the text to not be larger than the text widget screen
width and. But it the screen is scrolled horizontally, it will not work as
expected, the advantage over the above interface is that is considers font
characters width, while the other interface assumes fixed width characters.

        Notice that "auto formatting" with Auto Fill mode is done when
        pressing enter, but information isn't saved per paragraph, so
        if values of align or break columns are changed, trying to edit
        a text block with different configuration will not give the expected
        results.
        Also notice that lines starting with non printable characters aren't
        automatically formatted. This is helpful for some editing modes
        where symbols can be used before lines in a paragraph. If you don't
        need this feature, usually pressing Space or Tab is enough to put the
        cursor at the proper position.
  M-U   Upcase word at cursor position or next word.
  M-V or PageUp
        Move cursor to previous page.
  M-Y   Kill ring yank feature. Basically it will circulate over all
        text that has been cut in the current session. Keep pressing it
        until happy :-)
  M-Z   Scrolls one line down.
  M-D   Kill word at cursor position or next word.
  S-M-D Delete word at cursor position or next word.
        Does not go to the kill ring.
  M-H or M-Delete or M-Backspace.
        Kill word at cursor position or previous word.
  S-M-H or S-M-Delete or S-M-Backspace
        Delete word at cursor position or previous word.
        Does not go to the kill ring.
  M-.   Find definition/declaration of symbol string of selected text, and/or
        finds next tag when more than one definition exists for the symbol.
  M-< or Home
        Move cursor to beginning of file.
  M-> or End
        Move cursor to end of file.
  M-] or C-Down
        Move cursor to next paragraph.
  M-[ or C-Up
        Move cursor to previous paragraph.
  C-_ or C-X,U
        Undo.
        If enabled in the given textwidget. Not enabled by default in the
        message window and filename window, or any of the other text widgets
        in the several available dialogs.
  C-\ or C-Kanji
        Reconnect Input Method.
        In international mode (probably broken interface).
  S-Insert
        Insert PRIMARY selection from CUT_BUFFER0.
  C-Q
        Followed by any character, will insert the next typed character
        useful to insert control characters. For example C-Q,C-L will
        insert ^L at the cursor position.
  LeftMouseButton
        When pressed marks the start of a PRIMARY selection at CUTBUFFER0
        When moved while pressed extends the selection.
  MiddleMouseButton
        When pressed, inserts the PRIMARY selection at CUTBUFFER0 at
        the cursor position.
  RightMouseButton
        Can be used to adjust a selection done with LeftMouseButton.
  C-A,Tab
        If the loaded file has a indentation rules file, C or Lisp, xedit
        will reindent the line. Also, entering a fresh character on a
        newline should be enough to move the cursor to the proper position.
        To override it, you may need to use the C-U to multiply the action,
        as it will only indent if only one character was added.
  C-X,C-C or (Pressing the Quit button)
        Exits xedit.
        If there are unsaved files, a message will be printed asking to
        "exit" again, or save the files.
  C-X,C-E
        Execute lisp expression before the cursor position.
  C-X,C-F
        Changes keyboard input focus to the filename text input window.
        In this mode, pressing Tab will try to complete the filename
        being typed.
        When more than one match exists, pressing Tab again will display
        the directory navigation window.
        The initial search path usually is the basename of the file loaded
        in the current textwindow, or currently directory from where
        xedit was started if the *scratch* is the current "buffer".
        The character ~ can be used as a shortcut for the home directory
        and ~username will be replaced by the home directory of "username"
        if it exists.
  C-X,C-S or (Pressing the Save button)
        Saves the file in the current text window.
  C-X,Tab
        Indents the current paragraph.
        Use the C-U modifier to specify the number of spaces to insert
        or remove if the C-U parameter is negative.
  C-X,0
        Deletes the current window.
        The file being edited is not unloaded.
  C-X,1
        Deletes the other window.
        The file being edited is not unloaded.
  C-X,2
        Splits vertically the current window.
  C-X,3
        Splits vertically the current window.
  C-X,b
        Switch the contents of the current window to the next file in
        the list of loaded files.
  C-X,d
        Displays the directory listing window.
        In this window, it is possible to navigate in the file system
        to choose a file to edit.
        Usually, this is the same as pressing C-X,C-F,Tab
        See C-X,C-F for more information.
  C-X,k
        Unloads the file being edited.
        If the file has not been saved, a message will be displayed,
        asking to either press C-X,k again, or save the file
        The *scratch* buffer cannot be killed and will always
        prints a warning when exiting xedit. This is the expected behavior.
  C-X,o
        Switch input focus to the other window, making it the current one
        If the editor doesn't have splited windows, this command is ignored.
  Insert
        Switches between insert and overwrite mode.
        In overwrite mode text is typed over existing file contents,
        only extending the file contents when typing at the end of
        a line (or file).
  Escape
        Enters the line edit mode.
        In this mode it is possible to use regex expressions to search and
        replace the contents of the file loaded in the current text window.
        Refer to the xedit(1) manpage for more information of the regex
        expression format.
        Note that the regex used by xedit isn't IEEE Std 1003.2 compliant,
        and not compliant with most regex implementations in that it doesn't
        support some complex search patterns, usually involving patterns
        like ((.*)+)? that may require too much restarts or have several
        correct interpretations for multiple matches. Also, it always does
        minimal matching, and it is not configurable like in pcre, example:
        searching "a1a1a1" with the pattern "(.*)\d" will find "a1" and
        not "a1a1a1" as could be expected.
        Please refer to lisp/re/README for more information on the supported
        regex expressions.
  C-LeftMouseButton
        Displays the "File Menu" from where it is possible to select a
        new file to be edited in the current window.
  C-MiddleMouseButton
        Displays the "Edit Menu" that usually has the following options:
     +------------------+-------------+
     | Wrapping      -> | Never       |
     |                  | Line        |
     |                  | Word        |
     | Auto Fill        +-------------+
     |                  +-------------+
     | Justification -> | Left        |
     |                  | Right       |
     |                  | Center      |
     |                  | Full        |
     |                  +-------------+
     | Break Columns... |
     |                  +-------------+
     | Scrollbars    -> | Vertical    |
     |                  | Horizontal  |
     |                  +-------------+
     |                  +-------------+
     | Edit Mode     -> | Plain/None  |
     |                  | C/C++       |
     |                  | Lisp/Scheme |
     |                  | X imake     |
     |                  | Makefile    |
     |                  | Unix shell  |
     |                  | SGML        |
     |                  | HTML        |
     |                  | Man page    |
     |                  | X resource  |
     |                  | XF86Config  |
     |                  | RPM spec    |
     |                  | XFree86 log |
     |                  | Patch file  |
     +------------------+-------------+
        "Wrapping" is disabled if "Auto Fill" is enabled.
        "Justification" and "Break Columns..." are enabled if "Auto Fill"
        is also enabled.
        "Edit Mode" lists the available syntax highlight and indentation
        rules defined.
        Note that most of these options don't work in "international" mode.
        Several xedit interfaces works only with 8 bits encodings, and
        doesn't properly handle UTF-8.
  C-RightMouseButton
        Displays the "Option Menu".
        Currently the only option is an Ispell frontend.
  FourthMouseButton (usually also moving up the mouse wheel)
        Scroll one line down
  FifthMouseButton (usually also moving down the mouse wheel)
        Scroll one line up



      There  is   also   some   documentation   in   lisp/README,   lisp/TODO,
  lisp/re/README, lisp/re/tests.txt, and comments/justifications/wishlists for
  the cases the interpreter fail to give the proper result for a given test.

      The  lisp  interpreter  implements  most  of   a  standard  COMMON  LISP
  environment, but the  compiler generates only  byte code and  not everything
  can be compiled, in those cases the interpreter  does the work. Examples are
  constructs involving  UNWIND-PROTECT or  any  kind of  jump  outside of  the
  current function body.

      For more  information please  consult any  COMMON LISP  documentation or
  tutorial.



      Simple tutorial on writing a "foolang" syntax highlight mode for xedit.

  Create a file called foolang.lsp
  Add:
  --
  (require "syntax")
  (require "indent")
  (in-package "XEDIT")
  --
  to foolang.lsp
  Check the available files if you want a custom property, or to know about
  the available ones. One example is:
  --
  (defsynprop *prop-foolang*
    "foolang"
    :font       "fixed"
    :foreground "rgb:a/b/c"
    :background "rgb:1/2/3"
    :underline  t
    :overstrike t)
  --
  Check  lisp/modules/xedit.lsp  for   the  other  options,   like  subscript,
  superscript and/or combining XLFD properties.
  Create a syntax definition for foolang. Check the definition of defsyntax in
  lisp/modules/syntax.lsp for more details. One example for foolang is:
  --
  (defsyntax *foolang-mode* :foolang nil nil nil
    ;; use the sample property created for foolang whenever the string
    ;; foolang is found at the toplevel
    (syntoken "\\<foolang\\>" :property *prop-foolang*)

    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
    ;; process C style comments
    (syntoken "/*" :nospec t :begin :comment :contained t)
      ;; contained is an option to not "export" this definition to child
      ;; tables

    (syntable :comment *prop-comment* #'default-indent
      ;; #'default-indent means a very simple indent that follows indentation
      ;; of previous line. Use nil for no indentation

      ;; Don't start a new table, instead flag as an error if nested
      (syntoken "/*" :nospec t :property *prop-error*)
        ;; :nospec t sets the RE_NOSPEC flag for the regex, i.e. searches
        ;; a literal string, and * will not be a special character

      (syntoken "XXX|TODO|FIXME" :property *prop-annotation*)
        ;; just to make it easier to flag some important comment

      (syntoken "*/" :nospec t :switch -1)
        ;; The :switch argument is the number of tables to "pop", in
        ;; this case, we are at table :comment, and :switch -1 returns
        ;; to table :foolang, that is the "root" table
    )

    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
    ;; Process lisp comments that can nest
    (syntable :lisp-comment *prop-comment* nil

      ;; Start a comment, possibly nested
      (syntoken "#|" :nospec t :begin :lisp-comment)

      ;; Returns to previous comment in stack or to main :foolang table
      (syntoken "|#" :nospec t :switch -1)

      ;; For easier flagging important comments
      (syntoken "XXX|FIXME|TODO" :property *prop-annotation*)
    )

    ;; This is usually in the end of the list, but can be anywhere,
    ;; just that if it isn't at the end, conflicting rules are resolved
    ;; by declaration order
    (synaugment :lisp-comment)
      ;; Adds the :lisp-comment table to :foolang table

    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
    ;; Lisp like strings that don't need a \ at the end of the line
    (syntable :lisp-string *prop-string* nil
      ;; ignore a escaped " in the middle of the string
      (syntoken "\\\\.")
        ;; Note that no options are used, just keep using the current
        ;; property. Unfortunately, backslashes must be escaped twice.
        ;; Once for the lisp reader and once for the regex compiler.

      (syntoken "\"" :nospec: t :switch -1)
        ;; :nospec is used just to create a faster regex. switch -1
        ;; returns to the previous syntax table. It isn't an error to
        ;; try to go down the "root" table, but if that happens, it
        ;; probably means either wrong syntax definition of malformed input.
    )

    (synaugment :lisp-string)
      ;; Adds the :lisp-string table to :foolang table
      ;; Note that since there isn't a rule to start a string in the
      ;; :lisp-string table, it cannot nest, maybe because the ending
      ;; character is the starting character ? :-))

    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
    ;; C style string rules
    (syntable :string *prop-string* nil
      ;; Ignore escaped characters
      (syntoken "\\\\.")

    ;; Match, most, printf arguments.
    (syntoken "%%|%([+-]?\\d+)?(l?[deEfgiouxX]|[cdeEfgiopsuxX])"
        :property *prop-format*)
      ;; Just for fun. This makes easier to see printf formats in strings
      ;; *prop-format* is *prop-string* with the :underline option

    (syntoken "\\\\$")
    ;; a backslash extends the string to the next line

    ;; A nonscaped " inside a string finishes it, since this table doesn't
    ;; have sub tables, and cannot nest, should return to :foolang table
    ;; from here
    (syntoken "\"" :nospec t :switch -1)

    ;; This token rule starts a new table called :error because end of line
    ;; has been matched. Note that it is defined last, so that a line
    ;; ending with " or \ will be processed first.
    (syntoken ".?$" :begin :error)

    (synaugment :string)
      ;; Adds the :string table to :foolang table

    ;; This table is used by :string, but could be shared for other patterns
    ;; like characters constants, etc.
    ;; It uses :switch -2 because it is started inside the :string table,
    ;; but it is also a table, so, pops two tables from the table stack
    (syntable :error *prop-error* nil
	(syntoken "^.*$" :switch -2)
    )
  )
  --

      Indentation rules are significantly  more complex. I suggest  looking at
  lisp/modules/indent.lsp   for   the   macros   and   function   definitions;
  and lisp/modules/progmodes/lisp.lsp and lisp/modules/progmodes/c.lsp for two
  sample  implementations   of   indentation   for   Lisp/Scheme   and   C/C++
  respectively.

      Note also  that indentation  is parsed  backwards, what  can cause  some
  confusion, and make "visualization" of order or precedence of evaluation for
  rules harder to understand.

      A simple indentation rules definition for foolang could be:

  --
  (defindent *foolang-mode-indent* :foolang
    ;; This must be the first token and usually the only token matching
    ;; BOL (Beginning of Line)
    (indtoken "^\\s*"   :indent
      :code (or *offset* (setq *offset* (+ *ind-offset* *ind-length*))))
      ;; the keyword :indent is a pattern put on a list when there is
      ;; a match, so that later patterns can be "reduced" by some other
      ;; rule, i.e.:  (:indent :indent) could be reduced to (:indent)

    (indtoken "//.*$"   nil)
      ;; C++ style comment. Returning nil instead of a token basically
      ;; ignores the token, as it should not enter the reduction pattern
      ;; list

    ;; Sample C comment pattern
    (indtoken "*/" :ccomment :nospec t :begin :comment)
      ;; Note that the indaugment macro doesn't need to be used, and actually
      ;; would be an error. In this example, the indentation compiler checks
      ;; the :begin :comment and handles it internally, as it already needs
      ;; to check for things like typos, unreachable labels, detectable
      ;; non resolving rules, etc. There is runtime check also, so it should
      ;; never enter an infinite loop when trying to resolve reduction rules.
      ;; Check lisp/modules/indent.lsp:(compile-indent-table) for the
      ;; implementation and more comments.

    ;; Indentation rules also have stacked tables
    (indtable :comment
      (indtoken "/*" :ocomment :nospec t :switch -1))
      ;; Note that the name is :ocomment (open comment), but that the
      ;; the table is finished when matching the open comment pattern

    ;; A simple initialization of a variable used by the indentation rules
    (indinit       (parens 0))
      ;; This variable can be declared anywhere in the body of defindent,
      ;; It will be properly moved to a "variables declaration section"
      ;; when expanding and compiling the table.

    (indtoken "("  :oparen  :nospec t  :code (incf parens))
    (indtoken ")"  :cparen  :nospec t  :code (decf parens))
      ;; These two tokes add the patterns :oparen and :cparen to the
      ;; "pattern list", and also have code to remember the balancing
      ;; of parenthesis.


    ;; One of the simplest reduction rules :-)
    (indreduce nil
      t
      ((:comment)))
      ;; Once the boundings of a comment are found, just ignore it, like
      ;; what was done with the // pattern, but in that case, the boundings
      ;; were readily available.
      ;; The t (True) parameter means that this rule is always evaluated,
      ;; but conditional code may be used, and implicit code may be added
      ;; to the end of the indreduce macro.
      ;; Since it is a macro, code can be compiled to optimized bytecode
      ;; after the macro is expanded.

    (indinit    (indent 0))
      ;; Note that there is a special *indent* variable that should hold the
      ;; proper indentation value, but it may be required to "overwrite"
      ;; without forgetting that value, for things like:
      ;;
      ;;  foo(bar(baz(blah
      ;;      ^       ^
      ;;      |       |
      ;;      indent  |
      ;;              effective indentation to be used
      ;;
      ;; where it is desirable to align the code in the next line with the
      ;; last open parenthesis.


      Since the  interface is,  unfortunately,  complex enough  to not  expect
  casual users to have something like a $HOME/.xedit file,  if you want to add
  new modes, please check lisp/modules/xedit.lsp:*auto-modes*

      There is some documentation about the variable. It should be possible to
  change/update the variable from the lisp interface  in the *scratch* buffer,
  but for  safety, it  is suggested  that  if you  add new  rules, you  should
  restart  xedit  after  it.  Also  note  that  there   is  compiled  code  in
  lisp/xedit.c that expects that variable to follow an specific format.

      You may notice that several .lsp files  aren't "properly indented"; this
  is because the lisp indentation rules  file was made long after  most of the
  other files were done, and it was considered  a bad practice to gratuitously
  reindent all files.



      At the  time  of this  writing,  the ispell  interface  should be  again
  functional, but it may be required to use some  old ispell program to handle
  non utf8 text. But it should work properly for  the english language, and in
  international mode, should work with any language. But there are problems in
  international mode not fixed.

      I  (Paulo  Cesar)  considered  several  times   to   extend  the  normal
  textwidget to handle  utf8, but this  is probably  a lot of  work/time badly
  spent and I prefer  to work on other  personal projects, but still  xedit is
  the editor I use for programming. The XPRINT support unfortunately is broken
  due to it. Note that xedit,  like pretty much any other  Xaw application can
  be linked against  Xaw with  XPRINT support. In  the case  of xedit,  a flag
  could be used, like the "international" variable to, at runtime, disable all
  the related code, if required.

      Also at the time of this writing, the tags  interface was added, as well
  as several other bug fixes. The tags interface is documented in the manpage,
  but the action  shortcut may  not be clear.  The default  shortcut is  M-. .
  There is no support for more  than one tags file, or changing  the tags file
  at runtime. But  the code  should be  easy to  adapt for  this case,  as all
  related functions receive pointers to the appropriate structures. One option
  could be to descend  from the directory of  the loaded file searching  for a
  tags file, and then associate the file with the tags definition, if it isn't
  already loaded. Shouldn't be  hard to implement. For  "inter project" files,
  it should be better to  have one xedit window per  "project", i.e. searching
  the definition of something  like a libc  symbol should probably be  done in
  another xedit window.