summaryrefslogtreecommitdiff
path: root/README
diff options
context:
space:
mode:
authorPaulo Cesar Pereira de Andrade <pcpa@mandriva.com.br>2008-03-11 21:41:45 -0300
committerPaulo Cesar Pereira de Andrade <pcpa@mandriva.com.br>2008-07-02 19:02:50 -0300
commit19e3f51f9758e2708fb4abfa364b346591089bcd (patch)
tree91abe23d7382c263a52c68b10fb99f44492c36af /README
parent618a07e8131f49bbda77d2cfe5832218a561a5c8 (diff)
Add updated/meaningful README, COPYING and AUTHORS files.
Diffstat (limited to 'README')
-rw-r--r--README604
1 files changed, 604 insertions, 0 deletions
diff --git a/README b/README
index e69de29..4188af3 100644
--- a/README
+++ b/README
@@ -0,0 +1,604 @@
+ 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.