Commit 9a98df49 authored by Dave Cooper's avatar Dave Cooper
Browse files

Merge branch 'master' of github.com:genworks/gendl into devo

parents f96b726a 93b0fed1
Welcome to the Genworks® Gendl™ Environment
=========
Startup
=========
After some time, you should see a "GDL-USER>" command prompt.
A web server also starts by default on port 9000 of the local host,
which allows you to visit, for example:
http://localhost:9000/tasty
If you accept the default robot:assembly, then click the hover-over
"pencil" icon next to the robot in the tree, you should see a
wireframe rendering of a simplified android robot.
See "Troubleshooting" below if you experience trouble starting up.
================
Emacs and Gendl
================
Although you are free to use other editors or IDEs, spending some time
to get familiar with Emacs is the best small investment you can make
for working with a Lisp-based system like Gendl. Slime (Superior Lisp
Interaction Mode for Emacs) which works across all major OS platforms
and CL implementations and is well-supported by the Common Lisp
community. Genworks plans to continue adding specialized Gendl support
to Slime.
If you are new to Emacs, you can get a general Emacs Tutorial under
the Help menu above. After completing the Tutorial, try to practice
what you learned by forcing yourself not to use the mouse too much in
Emacs.
Touch-typing ability is definitely an asset for Gendl development, but
with auto-completion of symbols (possible with M-/ -- you'll know what
that means after looking at the tutorial) it is possible to become a
world-class Gendl developer without having world-class typing speed.
It is strongly recommended to map your Caps Lock key to be a Control
key. This will give you a much more comfortable experience, allowing
you to use all the Emacs navigation keystrokes without constantly
curling your left little finger down to the Control key. For Linux
and Mac, this is easy to do in your System Preferences. For Windows,
here are some resources which can help you do this (the first one
appears not to require Administrator access on your machine):
http://johnhaller.com/jh/useful_stuff/disable_caps_lock/
Note that if you are running Windows in a Virtual Machine hosted under
MacOS or Linux, it is sufficient to map the Caps Lock to to Control in
the host system.
Finally, please see the Genworks Documentation (URL below) for an
introductory video on using Emacs in the Gendl environment.
===============
Learning Gendl
===============
Absolutely the best way to learn Gendl is to dive in and start using
it for small exercises and projects.
The work-in-progress tutorial.pdf is shipped with this distribution.
Other Documentation:
http://www.genworks.com
Then click the link for Documentation.
=========
Quitting
=========
When you have had enough of using Gendl with Slime, you should do
two things:
1. type
M-x gdl-quit (and press <Return>)
from anywhere in Emacs, to kill the Gendl process.
2. (optional) type
C-x C-c (that's Control-x, Control-c)
to kill the Emacs process and exit the window.
3. If you kept Emacs up and running, it is possible to restart the
Gendl session again with "M-x gdl" or "M-x slime"
=================
Customizing Emacs
=================
If a file exists in your home directory called ".emacs-gendl" this will
be loaded upon startup. You can put any custom emacs-lisp code in this
file to customize your startup (see below for an example to customize
the color theme).
You can always find out where Emacs thinks is your home directory's
location by typing
C-x d ~/ <RET>
This should present the list of files in the home directory, and show
its full name on the first line. Likewise, to visit your init file,
type:
C-x C-f ~/.emacs-gendl <RET>.
Color Themes
============
Gendl comes packaged with the color-theme:
http://emacswiki.org/emacs/ColorTheme
package for Gnu emacs.
You can select any of the themes from color-theme with
M-x color-theme-select
(Click on the color theme you want to select then press <Return>).
To set a color theme automatically, put something like the following
at the end of your ~/.emacs-gendl :
(color-theme-bharadwaj) ;; for solarized dark theme, or
=========================
Emacs Keychord Reference
=========================
The following is a reference for the Emacs keychords which are
commonly used when working with Gendl. They will be understandable after
you have completed the Emacs Tutorial mentioned above. If you force
yourself to use these for a few days, they will quickly feel natural.
;;
;; Backing out of a command (important! use this whenever you are lost)
;;
C-g : quit the active command (use this if you ever get confused)
;;
;; Navigating Through the Buffer
;;
C-n : next line
C-p : previous line
C-f : forward char
M-f : forward word
C-M-f : forward s-expression
C-b : backward char
M-b : backward word
C-M-b : backward s-expression
C-a : begin of line
C-e : end of line
;;
;; Auto-completion
;;
M-/ : complete word
C-c ] : "super-bracket" -- close parens to enclosing toplevel.
;;
;; Copying, Cutting, Pasting, working with Lisp S-expressions
;;
C-d : delete character
M-d : delete word
C-M-k : kill s-expression
C-<space> : begins a selection
C-M-<space> : selects current sexpression
M-w : copies selection
C-w : cuts selection
C-y : yanks (pastes) the selection
M-y : yanks previous
C-k : kills current line
C-x u : Undo!
M-<space> : removes all but one whitespace under point.
M-\ : removes all whitespace under point.
;;
;; Indenting
;;
C-M-q indents entire expression (with cursor on opening parenthesis)
C-q indents and word-wraps a paragraph of text to reasonable line
length.
;;
;; Working with Files & Buffers
;;
C-x C-b : get list of open buffers
C-x k : kills current buffer
C-x b : visit other buffer (default is previous)
C-x C-s : saves current buffer to file
C-x C-w : saves current buffer to a new file
C-x C-f : find file (i.e. file open)
;;
;; Dired (Directory editor) mode
;;
C-x C-f to visit a directory, then <Enter> for Directory Editor (Dired)
Within Dired:
d : marks file for deletion
f : visits the file or directory
~ : marks all backup files for deletion
x : executes pending commands (usually deletions)
;;
;; Windows and Frames
;;
C-x 2 : split screen into two windows
C-x 1 : make current window be the only window
C-x 0 : close current window
C-x o : change to next window
C-x y : change to previous window
C-x 2 5 : Open a new Frame (a new desktop window)
C-x & : Jump to *gdl-devo* buffer
;;
;; Command-line Shortcuts
;;
M-p : bring back previous command
M-n : bring back next command
;;
;; Compiling and Loading from Buffer
;;
C-c C-k : Compile Buffer
C-c C-c : Compile current form (e.g. define-object or defun)
C-x C-e : Evaluate Form (with cursor after closing parenthesis)
Troubleshooting
===============
Webserver Fails to serve on Port 9000
First of all, you may receive a message from your Firewall asking
for permission to unblock services from the dx86cl64 executable. You
should grant this permission.
If you are unable to see the following URL:
http://localhost:9000/color-map
then it is possible your machine already has another process running
on Port 9000. For example, some online gaming software will set up a
proxy service on this port.
If this is the case, then you can start Gendl serving on a different
port. To do this, try the following at the "gdl-user>" command
prompt (using port 8888 as an example):
(net.aserve:shutdown)
(gwl:start-gwl :port 8888)
Now try visiting
http://localhost:8888/color-map
If this works, then you can put these commands into the gdlinit.cl
initialization file in your home directory.
This source diff could not be displayed because it is too large. You can view the blob instead.
;;; color-theme.el --- install color themes
;; Copyright (C) 1999, 2000 Jonadab the Unsightly One <jonadab@bright.net>
;; Copyright (C) 2000, 2001, 2002, 2003 Alex Schroeder <alex@gnu.org>
;; Copyright (C) 2003, 2004, 2005, 2006 Xavier Maillard <zedek@gnu.org>
;; Version: 6.6.0
;; Keywords: faces
;; Author: Jonadab the Unsightly One <jonadab@bright.net>
;; Maintainer: Xavier Maillard <zedek@gnu.org>
;; URL: http://www.emacswiki.org/cgi-bin/wiki.pl?ColorTheme
;; This file is not (YET) part of GNU Emacs.
;; This is free software; you can redistribute it and/or modify it under
;; the terms of the GNU General Public License as published by the Free
;; Software Foundation; either version 2, or (at your option) any later
;; version.
;;
;; This is distributed in the hope that it will be useful, but WITHOUT
;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
;; FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
;; for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to the
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
;; MA 02111-1307, USA.
;;; Commentary:
;; Please read README and BUGS files for any relevant help.
;; Contributors (not themers) should also read HACKING file.
;;; Thanks
;; Deepak Goel <deego@glue.umd.edu>
;; S. Pokrovsky <pok@nbsp.nsk.su> for ideas and discussion.
;; Gordon Messmer <gordon@dragonsdawn.net> for ideas and discussion.
;; Sriram Karra <karra@cs.utah.edu> for the color-theme-submit stuff.
;; Olgierd `Kingsajz' Ziolko <kingsajz@rpg.pl> for the spec-filter idea.
;; Brian Palmer for color-theme-library ideas and code
;; All the users that contributed their color themes.
;;; Code:
(eval-when-compile
(require 'easymenu)
(require 'reporter)
(require 'sendmail))
(require 'cl); set-difference is a function...
;; for custom-face-attributes-get or face-custom-attributes-get
(require 'cus-face)
(require 'wid-edit); for widget-apply stuff in cus-face.el
(defconst color-theme-maintainer-address "zedek@gnu.org"
"Address used by `submit-color-theme'.")
;; Emacs / XEmacs compatibility and workaround layer
(cond ((and (facep 'tool-bar)
(not (facep 'toolbar)))
(put 'toolbar 'face-alias 'tool-bar))
((and (facep 'toolbar)
(not (facep 'tool-bar)))
(put 'tool-bar 'face-alias 'toolbar)))
(defvar color-theme-xemacs-p (and (featurep 'xemacs)
(string-match "XEmacs" emacs-version))
"Non-nil if running XEmacs.")
;; Add this since it appears to miss in emacs-2x
(if (fboundp 'replace-in-string)
(defalias 'color-theme-replace-in-string 'replace-in-string)
(defsubst color-theme-replace-in-string (target old new &optional literal)
(replace-regexp-in-string old new target nil literal)))
;; face-attr-construct has a problem in Emacs 20.7 and older when
;; dealing with inverse-video faces. Here is a short test to check
;; wether you are affected.
;; (set-background-color "wheat")
;; (set-foreground-color "black")
;; (setq a (make-face 'a-face))
;; (face-spec-set a '((t (:background "white" :foreground "black" :inverse-video t))))
;; (face-attr-construct a)
;; => (:background "black" :inverse-video t)
;; The expected response is the original specification:
;; => (:background "white" :foreground "black" :inverse-video t)
;; That's why we depend on cus-face.el functionality.
(cond ((fboundp 'custom-face-attributes-get)
(defun color-theme-face-attr-construct (face frame)
(if (atom face)
(custom-face-attributes-get face frame)
(if (and (consp face) (eq (car face) 'quote))
(custom-face-attributes-get (cadr face) frame)
(custom-face-attributes-get (car face) frame)))))
((fboundp 'face-custom-attributes-get)
(defalias 'color-theme-face-attr-construct
'face-custom-attributes-get))
(t
(defun color-theme-face-attr-construct (&rest ignore)
(error "Unable to construct face attributes"))))
(defun color-theme-alist (plist)
"Transform PLIST into an alist if it is a plist and return it.
If the first element of PLIST is a cons cell, we just return PLIST,
assuming PLIST to be an alist. If the first element of plist is not a
symbol, this is an error: We cannot distinguish a plist from an ordinary
list, but a list that doesn't start with a symbol is certainly no plist
and no alist.
This is used to make sure `default-frame-alist' really is an alist and not
a plist. In XEmacs, the alist is deprecated; a plist is used instead."
(cond ((consp (car plist))
plist)
((not (symbolp (car plist)))
(error "Wrong type argument: plist, %S" plist))
((featurep 'xemacs)
(plist-to-alist plist)))); XEmacs only
;; Customization
(defgroup color-theme nil
"Color Themes for Emacs.
A color theme consists of frame parameter settings, variable settings,
and face definitions."
:version "20.6"
:group 'faces)
(defcustom color-theme-legal-frame-parameters "\\(color\\|mode\\)$"
"Regexp that matches frame parameter names.
Only frame parameter names that match this regexp can be changed as part
of a color theme."
:type '(choice (const :tag "Colors only" "\\(color\\|mode\\)$")
(const :tag "Colors, fonts, and size"
"\\(color\\|mode\\|font\\|height\\|width\\)$")
(regexp :tag "Custom regexp"))
:group 'color-theme
:link '(info-link "(elisp)Window Frame Parameters"))
(defcustom color-theme-legal-variables "\\(color\\|face\\)$"
"Regexp that matches variable names.
Only variables that match this regexp can be changed as part of a color
theme. In addition to matching this name, the variables have to be user
variables (see function `user-variable-p')."
:type 'regexp
:group 'color-theme)
(defcustom color-theme-illegal-faces "^w3-"
"Regexp that matches face names forbidden in themes.
The default setting \"^w3-\" excludes w3 faces since these
are created dynamically."
:type 'regexp
:group 'color-theme
:link '(info-link "(elisp)Faces for Font Lock")
:link '(info-link "(elisp)Standard Faces"))
(defcustom color-theme-illegal-default-attributes '(:family :height :width)
"A list of face properties to be ignored when installing faces.
This prevents Emacs from doing terrible things to your display just because
a theme author likes weird fonts."
:type '(repeat symbol)
:group 'color-theme)
(defcustom color-theme-is-global t
"*Determines wether a color theme is installed on all frames or not.
If non-nil, color themes will be installed for all frames.
If nil, color themes will be installed for the selected frame only.
A possible use for this variable is dynamic binding. Here is a larger
example to put in your ~/.emacs; it will make the Blue Sea color theme
the default used for the first frame, and it will create two additional
frames with different color themes.
setup:
\(require 'color-theme)
;; set default color theme
\(color-theme-blue-sea)
;; create some frames with different color themes
\(let ((color-theme-is-global nil))
\(select-frame (make-frame))
\(color-theme-gnome2)
\(select-frame (make-frame))
\(color-theme-standard))
Please note that using XEmacs and and a nil value for
color-theme-is-global will ignore any variable settings for the color
theme, since XEmacs doesn't have frame-local variable bindings.
Also note that using Emacs and a non-nil value for color-theme-is-global
will install a new color theme for all frames. Using XEmacs and a
non-nil value for color-theme-is-global will install a new color theme
only on those frames that are not using a local color theme."
:type 'boolean
:group 'color-theme)
(defcustom color-theme-is-cumulative t
"*Determines wether new color themes are installed on top of each other.
If non-nil, installing a color theme will undo all settings made by
previous color themes."
:type 'boolean
:group 'color-theme)
(defcustom color-theme-directory nil
"Directory where we can find additionnal themes (personnal).
Note that there is at least one directory shipped with the official
color-theme distribution where all contributed themes are located.
This official selection can't be changed with that variable.
However, you still can decide to turn it on or off and thus,
not be shown with all themes but yours."
:type '(repeat string)
:group 'color-theme)
(defcustom color-theme-libraries (directory-files
(concat
(file-name-directory (locate-library "color-theme"))
;;; Debian doesn't use the "/themes" subdirectory and uses the prefix
;;; "^color-theme-" instead of simply "^color-theme" to accomodate this.
"") t "^color-theme-")
"A list of files, which will be loaded in color-theme-initialize depending
on `color-theme-load-all-themes' value.
This allows a user to prune the default color-themes (which can take a while
to load)."
:type '(repeat string)
:group 'color-theme)
(defcustom color-theme-load-all-themes t
"When t, load all color-theme theme files
as presented by `color-theme-libraries'. Else
do not load any of this themes."
:type 'boolean
:group 'color-theme)
(defcustom color-theme-mode-hook nil
"Hook for color-theme-mode."
:type 'hook
:group 'color-theme)
(defvar color-theme-mode-map
(let ((map (make-sparse-keymap)))
(define-key map (kbd "RET") 'color-theme-install-at-point)
(define-key map (kbd "c") 'list-colors-display)
(define-key map (kbd "d") 'color-theme-describe)
(define-key map (kbd "f") 'list-faces-display)
(define-key map (kbd "i") 'color-theme-install-at-point)
(define-key map (kbd "l") 'color-theme-install-at-point-for-current-frame)
(define-key map (kbd "p") 'color-theme-print)
(define-key map (kbd "q") 'bury-buffer)
(define-key map (kbd "?") 'color-theme-describe)
(if color-theme-xemacs-p
(define-key map (kbd "<button2>") 'color-theme-install-at-mouse)
(define-key map (kbd "<mouse-2>") 'color-theme-install-at-mouse))
map)
"Mode map used for the buffer created by `color-theme-select'.")
(defvar color-theme-initialized nil
"Internal variable determining whether color-theme-initialize has been invoked yet")
(defvar color-theme-buffer-name "*Color Theme Selection*"
"Name of the color theme selection buffer.")
(defvar color-theme-original-frame-alist nil
"nil until one of the color themes has been installed.")
(defvar color-theme-history nil
"List of color-themes called, in reverse order")
(defcustom color-theme-history-max-length nil
"Max length of history to maintain.
Two other values are acceptable: t means no limit, and
nil means that no history is maintained."
:type '(choice (const :tag "No history" nil)
(const :tag "Unlimited length" t)
integer)
:group 'color-theme)
(defvar color-theme-counter 0
"Counter for every addition to `color-theme-history'.
This counts how many themes were installed, regardless
of `color-theme-history-max-length'.")
(defvar color-theme-entry-path (cond
;; Emacs 22.x and later
((lookup-key global-map [menu-bar tools])
'("tools"))
;; XEmacs
((featurep 'xemacs)
(setq tool-entry '("Tools")))
;; Emacs < 22
(t
'("Tools")))
"Menu tool entry path.")
(defun color-theme-add-to-history (name)
"Add color-theme NAME to `color-theme-history'."
(setq color-theme-history
(cons (list name color-theme-is-cumulative)
color-theme-history)
color-theme-counter (+ 1 color-theme-counter))
;; Truncate the list if necessary.
(when (and (integerp color-theme-history-max-length)
(>= (length color-theme-history)
color-theme-history-max-length))
(setcdr (nthcdr (1- color-theme-history-max-length)
color-theme-history)
nil)))
;; (let ((l '(1 2 3 4 5)))
;; (setcdr (nthcdr 2 l) nil)
;; l)
;; List of color themes used to create the *Color Theme Selection*
;; buffer.
(defvar color-themes
'((color-theme-aalto-dark "Aalto Dark" "Jari Aalto <jari.aalto@poboxes.com>")
(color-theme-aalto-light "Aalto Light" "Jari Aalto <jari.aalto@poboxes.com>")
(color-theme-aliceblue "Alice Blue" "Girish Bharadwaj <girishb@gbvsoft.com>")
(color-theme-andreas "Andreas" "Andreas Busch <Andreas.Busch@politics.ox.ac.uk>")
(color-theme-arjen "Arjen" "Arjen Wiersma <arjen@wiersma.org>")
(color-theme-beige-diff "Beige Diff" "Alex Schroeder <alex@gnu.org>" t)
(color-theme-bharadwaj "Bharadwaj" "Girish Bharadwaj <girishb@gbvsoft.com>")