# HG changeset patch # User Oleksandr Gavenko # Date 1324330813 -7200 # Node ID 3059b0c6c39af77f694d4f8e09c7e6b921f93542 # Parent 7c5ca700ff028bfc11aa4c2ceba0167b1e894528 symbol-plist diff -r 7c5ca700ff02 -r 3059b0c6c39a emacs.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/emacs.rst Mon Dec 19 23:40:13 2011 +0200 @@ -0,0 +1,542 @@ +.. -*- coding: utf-8; -*- + +======== + Emacs. +======== +.. contents:: + +About. +====== + + http://elpa.gnu.org/ + Packages for Emacs. This requires Emacs version 24.1 or + higher. + +Getting help. +============= + + * http://news.gmane.org/gmane.emacs.help + * http://news.gmane.org/gmane.emacs.announce + * http://news.gmane.org/gmane.emacs.auctex.announce + +Installing Emacs. +================= + + http://ftp.gnu.org/gnu/emacs/windows/ + Clean GNU Emacs for 32-bit Windows + http://emacsformacosx.com/ + Clean GNU Emacs for Mac OS X + +Variables. +========== + +Select one of:: + + (set 'variable value) + (setq variable value) + (defvar variable value "documentation") + +or (replace with:: + + # Local variables + # variable value + # End + +Debugging. +========== + +Evaluating elisp expression on the fly. +--------------------------------------- + +Type M-: than lisp expression than type RET. + +Or in any buffer place point at the end of lisp expression and type C-x C-e. + +Or invoke elisp "shell" by M-x ielm. + +What functions and variables Emacs load and from which files? +------------------------------------------------------------- + +See value of variable ``load-history`` (by C-h v load-history RET). + +Using edebug. +------------- + +Execute ``M-x edebug-defun`` (also on ``C-u C-M-x``) on defun in source code to +enable debugging for desired function. When next time this function invoked +you entered to its debugging (jumped to its source code). + +To start debug execute code which used debugged function. + +You can disable edebug on a function by evaluating the function again using +``C-M-x``. + +How debug func? +--------------- + +Use M-x debug-on-entry and M-x cancel-debug-on-entry to control +which functions will enter the debugger when called. + +When next time that function called automatically loaded debug-mode. + +How debug ini file? +------------------- + +When your ini has a bug, or when you load external files that cause +errors, the bug is often hard to find, because the Emacs Lisp reader does not +know about line numbers and files - it just knows an error happened, and +that's it. + +Try run Emacs with ``--debug-init`` to see backtrace. + +How debug long running command? +------------------------------- + +M-x debug-on-quit RET`` and then just hit `C-g`` next time it gets ``stuck`` +somewhere. + +Check if bug in ini file not in Emacs itself. +--------------------------------------------- + +First run Emacs without loading anything:: + + $ emacs --no-init-file --no-site-file + +or more shortly (as ``-Q`` imply ``-q``, ``--no-site-file``, and ``--no-splash`` +together):: + + $ emacs -Q + +If bug not reproduced bug lies in ini files! + +Debug by binary search. +----------------------- + +Select half of the file in a region, and M-x eval-region. Depending on whether +that causes the error or not, split this half or the other half again, and +repeat. + +Simplified Binary Search. +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Add (error ``No error until here``) in the middle of your file. If you get the +error ``No error until here`` when reloading the file, move the expression +towards the back of the file, otherwise towards the front of the file. + +Elisp debug tips. +----------------- + + - Use a keyboard macro that moves forward one expression (sexp) and evaluates + it. + - Try C-x check-parens. + +Enable debug mode (also on loading). +------------------------------------ + +Set in source:: + + (setq debug-on-error t) + +or invoke Emacs like:: + + $ emacs --debug-init + +where ``--debug-init`` binds ``debug-on-error`` to ``t`` while loading the init +file, and bypasses the ``condition-case`` which normally catches errors in the +init file. + +Call tree. +---------- + +Before byte compiling file execute:: + + (setq byte-compile-generate-call-tree t) + +Veiw buffer local variables. +---------------------------- +:: + + (pp (buffer-local-variables)) + +Emacs profiling. +================ + +benchmark.el. +------------- +:: + + (benchmark-run 1 (revert-buffer)) + +elp.el. +------- + +Enter a prefix for ``M-x elp-instrument-package``, perform action and see result +by ``M-x elp-results``. To perform new measurement don't forget to run +``M-x elp-reset-all``. + +WWW. +==== + +Text based WWW browser. +----------------------- + + http://en.wikipedia.org/wiki/W3m + http://emacs-w3m.namazu.org/ + http://www.gnu.org/software/w3/ + +Tricks. +======= + +Sort and uniquify lines. +------------------------ + +Select region, type ``C-u M-| sort -u RET``. + +With transient-mark-mode and delete-selection-mode enabled: select region, +type M-| sort -u RET to replace selection with sorted and uniquified lines. + +Determining running environment/platform. +========================================= + +Check variables:: + + emacs-major-version + emacs-minor-version + window-system - ``nil`` if in terminal, ``w32`` if native Windows build, ``x`` if under X Window + window-system-version - for windows only + window-size-fixed + operating-system-release - release of the operating system Emacs is running on + system-configuration - like configuration triplet: cpu-manufacturer-os + system-configuration-options + system-name - host name of the machine you are running on + system-time-locale + system-type - indicating the type of operating system you are using: + ``gnu`` (GNU Hurd), + ``gnu/linux``, + ``gnu/kfreebsd``, ``berkeley-unix`` for (FreeBSD), + ``darwin`` (GNU-Darwin, Mac OS X), + ``ms-dos``, + ``windows-nt``, + ``cygwin`` + system-uses-terminfo + dynamic-library-alist or deprecated image-library-alist + - alist of image types vs external libraries needed to display them + +and check functions:: + + (fboundp ...) - return t if SYMBOL's function definition is not void + (featurep ...) - returns t if FEATURE is present in this Emacs + (display-graphic-p) - return non-nil if DISPLAY is a graphic display; graphical + displays are those which are capable of displaying several + frames and several different fonts at once + (display-multi-font-p) - same as ``display-graphic-p`` + (display-multi-frame-p) - same as ``display-graphic-p`` + (display-color-p) - return t if DISPLAY supports color + (display-images-p) - return non-nil if DISPLAY can display images + (display-grayscale-p) - return non-nil if frames on DISPLAY can display shades of gray + (display-mouse-p) - return non-nil if DISPLAY has a mouse available + (display-popup-menus-p) - return non-nil if popup menus are supported on DISPLAY + (display-selections-p) - return non-nil if DISPLAY supports selections + +Run those checks as below:: + + (when window-system ...) + (when (eq window-system 'x) ...) + (when (>= emacs-major-version 22) ...) + (when (fboundp '...) ...) + (when (featurep '...) ...) + +Compiling emacs. +================ + +Windows. +-------- + +Get MSYS for POSIX shell and utilities . Get MinGW for GCC. Get Gnuwin32 for +jpeg, ungif, tiff, xpm, png, zlib libraries. + +Read emacs/nt/INSTALL:: + + $ cmd + $ cd emacs\nt + $ configure.bat --prefix %INST_ROOT% --with-gcc --cflags -I%GNUWIN32_ROOT%/include --ldflags -L%GNUWIN32_ROOT%/lib --ldflags -lregex + $ make bootstrap + $ make info + $ make install + +Documentation. +============== + +Elisp documentation. +-------------------- +:: + + ;;; .el --- + + ;; Copyright (C) + + ;; Author: + ;; Maintainer: + ;; Created: + ;; Version: + ;; Keywords: + ;; URL: + + ;;; Commentary: + + ;;; Code: + + ;;; ends here + +See + + * http://www.gnu.org/software/emacs/elisp-manual/html_node/Library-Headers.html + * http://www.emacswiki.org/cgi-bin/wiki/ElispAreaConventions + +CheckDoc. +--------- + +CheckDoc checks your EmacsLisp code for errors in documentation and style. + + http://cedet.sourceforge.net/checkdoc.shtml + home page before including it into GNU Emacs + http://www.emacswiki.org/emacs/CheckDoc + CheckDoc + +Installing Emacs. +================= + +From sources. +------------- + + http://ftp.gnu.org/pub/gnu/emacs + +Windows. +-------- + + http://ftp.gnu.org/pub/gnu/emacs/windows + Releases for Windows. + http://alpha.gnu.org/gnu/emacs/windows + Beta releases for Windows. + +Debian. +------- +:: + + $ apt-get install emacs + +Emacs paths. +============ +:: + + source-directory data-directory doc-directory exec-directory + invocation-directory trash-directory tutorial-directory user-emacs-directory + widget-image-directory + +Emacs games. +============ +:: + + hanoi hanoi-unix life pong tetris gomoku + +Long lines. +=========== + + (setq longlines-show-hard-newlines t) + (setq longlines-wrap-follows-window-size t) + (longlines-mode 1) + +Printing Emacs structures. +========================== + + (message "%S" '(a b 123 "hello" 'set)) + (pp '(a b 123 "hello" 'set)) + (prin1-to-string '(1 2)) + + (symbol-name 'f) + (symbol-value 'f) + (symbol-function 'f) + (symbol-plist 'f) + +File manager. +============= + + http://www.emacswiki.org/emacs/Sunrise_Commander + +Semantic. +========= + + semantic-lex-spp-describe + Describe the current list of spp macros. + semantic-lex-c-preprocessor-symbol-file + List of C/C++ files that contain preprocessor macros for the C lexer. + +Debugging C code. +================= + + -*- mode: grep; mode: auto-revert-tail; default-directory: "~/devel/proj" -*- + +XML modes. +========== + +XSLT-process. +------------- + +XSLT-process is a minor mode for GNU Emacs/XEmacs which transforms it into a powerful editor with +XSLT processing and debugging capabilities. + +The mode currently supports two Java XSLT processors: + + * Saxon - fully supported, including debugging capabilities. + * Xalan - fully supported, including debugging capabilities. + + http://xslt-process.sourceforge.net/ + home page + +Useful program logging. +======================= + +Put first line to your log file, you must replace ``default-directory`` to dir where you build +program:: + + -*- mode: compilation-minor; mode: auto-revert-tail; default-directory: "~/devel/proj" -*- + +Program must use one of supported by ``compilation-minor-mode`` (see +``compilation-error-regexp-alist``), like:: + + printf(__FILE__ ":%d: %s\n", __LINE__, msg); /* msg - user defined string */ + +or in second form (in this case line number included in format string, so easy searchable in +debugger):: + + #define NUM2STR(x) STR(x) + #define STR(x) #x + + printf(__FILE__ ":" NUM2STR(__LINE__) ": %s\n", msg); + +Or some faster use ``grep-mode``, but you restricted with GNU like error format:: + + -*- mode: grep; mode: auto-revert-tail; default-directory: "~/devel/proj" -*- + +Edit HTML. +========== + + * psgml-mode + * nxml-mode + * sgml-mode + +html-helper-mode. +----------------- + +Highlighting, autocompletion, and auto-insertion of closing tags. + + http://www.emacswiki.org/emacs/HtmlHelperMode + http://savannah.nongnu.org/projects/baol-hth/ + http://www.nongnu.org/baol-hth/ + +Source. +======= + +Get main development sources:: + + $ bzr init-repo --2a emacs + $ cd emacs + $ bzr branch http://bzr.savannah.gnu.org/r/emacs/trunk trunk + $ cd trunk + $ bzr bind http://bzr.savannah.gnu.org/r/emacs/trunk + +To update with latest changes:: + + $ cd emacs/trunk + $ bzr update + +See: + + http://www.emacswiki.org/emacs/BzrForEmacsDevs + +Emacs Git mirror. +----------------- + + http://www.emacswiki.org/emacs/EmacsFromGit + +Patch. +====== + + http://debbugs.gnu.org/cgi/bugreport.cgi?bug=5719 + [patch] fix bat-generic-mode highlighting pattern for CLI + switch. + +How report bug. +=============== + +Visit http://debbugs.gnu.org or M-x report-emacs-bug. + + +Finding emacs packages. +======================= + + * http://anc.ed.ac.uk/~stephen/emacs/ell.html + * http://www.emacswiki.org/emacs/WikifiedEmacsLispList + * http://www.emacswiki.org/emacs/RationalElispPackaging + + http://tromey.com/elpa/index.html + Emacs Lisp Package Archive + + +EPLA. +----- + +ELPA goal is to make it simple to install, use, and upgrade Emacs Lisp packages. + + + +Currently (2011-02-15) available such sources:: + + (setq package-archives '(("ELPA" . "http://tromey.com/elpa/") + ("gnu" . "http://elpa.gnu.org/packages/") + ("marmalade" . "http://marmalade-repo.org/packages/") + )) + + * http://www.emacswiki.org/emacs/ELPA + * http://marmalade-repo.org/ + + http://elpa.gnu.org/ + official GNU Emacs Lisp Package Archive + http://tromey.com/elpa/ + old Emacs Lisp Package Archive home page + http://tromey.com/elpa/upload.html + how to contribute + +Emacswiki. +---------- + + http://www.emacswiki.org/emacs/ElispArea + http://www.emacswiki.org/emacs/WikifiedEmacsLispList + +emacsmirror. +------------ + + https://github.com/emacsmirror/p/wiki + http://www.emacsmirror.org/ + http://www.emacswiki.org/emacs/Emacsmirror + +Funny Emacs modes. +================== + + glasses + Minor mode for making identifiers likeThis readable. + +Useful commands. +================ +:: + + flush-lines keep-lines + align-regexp + C-x C-o + M-PageUp/M-PageDown + command-history + M-= + C-x l + locate-library find-library + features load-history +