xemacs-packages
New package: guided-tour
This package provides slides from Phil Sung's "Guided Tour of Emacs",
downloaded from
http://stuff.mit.edu/iap/emacs/ on February 18, 2007.
The slides are available in both PDF and Open Document presentation
format. HTML and a updated HTML version are likely to be added later.
A few comments on the sample package I posted are still trickling in,
and I'm still hoping for comments from Phil Sung, so I'll delay a
commit for a couple of days.
There's one minor potential issue. This package inserts references to
itself in the menubar Help menu via auto-autoloads; technically I
suppose that could be considered a violation of the policy that
packages shouldn't activate themselves, but I can't see any harm in
hooking new items into the menus.
For the future, besides improvements to the package itself, I hear
that GNU Emacs will be putting a pointer to the Guided Tour in the
splash screen. Seems like a good idea to me (independent of keeping
up with the Gnubies). What do others think?
The patch provided here contains only the package infrastructure and
elisp file that insinuates the menubar. A prototype version of the
package is available at
http://turnbull.sk.tsukuba.ac.jp/Tools/XEmacs/guided-tour/
cvs diff -U 0 -N ChangeLog .cvsignore Makefile package-info.in guided-tour.el
Index: ChangeLog
===================================================================
RCS file: ChangeLog
diff -N ChangeLog
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ ChangeLog 4 May 2007 10:51:57 -0000
@@ -0,0 +1,30 @@
+2007-05-03 Stephen J. Turnbull <stephen(a)xemacs.org>
+
+ Create package.
+
+ * emacs-slides-1.odp:
+ * emacs-slides-2.odp:
+ * emacs-slides-3.odp:
+ * emacs-slides-1.pdf:
+ * emacs-slides-2.pdf:
+ * emacs-slides-3.pdf:
+ Import Phil Sung's "Guided Tour" content, from
+
http://stuff.mit.edu/iap/emacs/ @2007-02-18T09:15.
+
+ Note: Phil graciously licensed these to XEmacs under the MIT/X11
+ license allowing us to use *these versions only* in any way we
+ might want to inside of XEmacs (specifically, we can freely use
+ this content in our Texinfo manuals), but asks that we distribute
+ only under the GPL or GFDL or both. The content is copyright-
+ assigned to the FSF, and is publicly licensed only under the GPL
+ and GFDL (as of this writing). When in doubt as to the intent of
+ the permissions for use of content, ask Phil first, don't rely on
+ the letter of the law or licenses.
+
+ * package-info.in:
+ * Makefile:
+ * ChangeLog:
+ New. Package infrastructure.
+
+ * guided-tour.el:
+ New. Menuing infrastructure.
Index: .cvsignore
===================================================================
RCS file: .cvsignore
diff -N .cvsignore
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ .cvsignore 4 May 2007 10:51:57 -0000
@@ -0,0 +1,4 @@
+#.*#
+.#*
+*~
+*.elc
Index: Makefile
===================================================================
RCS file: Makefile
diff -N Makefile
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ Makefile 4 May 2007 10:51:57 -0000
@@ -0,0 +1,34 @@
+# Makefile for the Guided Tour to Emacs
+
+# This file is part of XEmacs.
+
+# XEmacs 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.
+
+# XEmacs 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 XEmacs; see the file COPYING. If not, write to
+# the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+
+VERSION = 0.50
+AUTHOR_VERSION =
+MAINTAINER = XEmacs Development Team <xemacs-beta(a)xemacs.org>
+PACKAGE = guided-tour
+PKG_TYPE = regular
+REQUIRES =
+CATEGORY = standard
+
+ELCS = guided-tour.elc
+
+DATA_FILES = emacs-slides-1.pdf emacs-slides-2.pdf emacs-slides-3.pdf \
+ emacs-slides-1.odp emacs-slides-2.odp emacs-slides-3.odp
+DATA_DEST = guided-tour
+
+include ../../XEmacs.rules
Index: package-info.in
===================================================================
RCS file: package-info.in
diff -N package-info.in
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ package-info.in 4 May 2007 10:51:57 -0000
@@ -0,0 +1,19 @@
+(guided-tour
+ (standards-version 1.1
+ version VERSION
+ author-version AUTHOR_VERSION
+ date DATE
+ build-date BUILD_DATE
+ maintainer MAINTAINER
+ distribution xemacs
+ priority high
+ category CATEGORY
+ dump nil
+ description "Phil Sung's Guided Tour of Emacs."
+ filename FILENAME
+ md5sum MD5SUM
+ size SIZE
+ provides (guided-tour)
+ requires (REQUIRES)
+ type regular
+))
Index: guided-tour.el
===================================================================
RCS file: guided-tour.el
diff -N guided-tour.el
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ guided-tour.el 4 May 2007 10:51:57 -0000
@@ -0,0 +1,189 @@
+;;; guided-tour.el --- functions for viewing Phil Sung's Emacs Guided Tour
+
+;; Copyright 2007 Free Software Foundation, Inc.
+
+;; Author: Stephen J. Turnbull <stephen(a)xemacs.org>
+;; Maintainer: XEmacs Development Team
+;; Created: 2007-05-02
+;; Keywords: doc
+
+;; The permissions notice is contained in the function
+;; `guided-tour-about' at the end of this file. Under the terms
+;; granted, you may modify that function, but the appropriate
+;; permissions notice must remain in this file somewhere.
+
+;;; Synched up with: Not in FSF.
+
+;;; Commentary:
+
+;; Thanks to Jason Spiro and Phil Sung for making substantial effort
+;; to make this content as useful to XEmacs as possible.
+
+;;; Code:
+
+;; Variables
+
+(defgroup guided-tour nil "Phil Sung's Emacs Guided Tour")
+
+(defcustom guided-tour-odp-viewer "ooimpress"
+ "Path to program able to view Open Document Format presentations.
+Program is invoked in a shell, so PATH is searched."
+:type '(choice string
+ (const "ooimpress")
+ (const "open" :doc "Useful on Mac OS X"))
+:group 'guided-tour)
+
+(defcustom guided-tour-pdf-viewer "xpdf"
+ "Path to program able to view Portable Document Format documents.
+Program is invoked in a shell, so PATH is searched."
+:type '(choice string
+ (const "xpdf")
+ (const "gv")
+ (const "open" :doc "Useful on Mac OS X"))
+:group 'guided-tour)
+
+(defconst guided-tour-submenu
+ '("A Guided Tour of Emacs"
+ ["Guided Tour, Part %_1 (OOo)" guided-tour-odp-1]
+ ["Guided Tour, Part %_2 (OOo)" guided-tour-odp-2]
+ ["Guided Tour, Part %_3 (OOo)" guided-tour-odp-3]
+ ["Guided Tour, Part %_1 (PDF)" guided-tour-pdf-1]
+ ["Guided Tour, Part %_2 (PDF)" guided-tour-pdf-2]
+ ["Guided Tour, Part %_3 (PDF)" guided-tour-pdf-3]
+ ["About COPYING the Tour" guided-tour-about])
+ "The submenu for Phil Sung's \"Guided Tour of Emacs\".")
+
+(defvar guided-tour-insinuate-menubar nil
+ "If non-nil, inhibits insinuation of the menubar.
+Note that if you make this nil and reinsinuate, you are responsible for
+removing any existing instances of the submenu.")
+
+;; Functions
+
+;; Helper functions
+
+;; #### this probably should move to help.el or menubar-items.el
+(defun guided-tour-find-menubar-help-menu (&optional menubar)
+ "Return the Help submenu for MENUBAR if present, else nil."
+ (assoc "%_Help" (or menubar default-menubar)))
+
+(defun guided-tour-about-xemacs-index (menu)
+ "Return the (zero-based) index of the About XEmacs item in MENU.
+Returns nil if not present."
+ ;; #### Of course we should actually search for it....
+ ;; Does easy-menu provide functions for this? It should....
+ (let ((item (cadr menu)))
+ (if (and (vectorp item) (eq 'about-xemacs (aref item 1)))
+ 0
+ nil)))
+
+;; Initialization
+
+;;;###autoload
+(defun guided-tour-insinuate-menubar ()
+ "Add Phil Sung's Guided Tour of Emacs to the default menubar."
+ (unless guided-tour-insinuate-menubar
+ (setq guided-tour-insinuate-menubar t)
+ (let* ((help (guided-tour-find-menubar-help-menu)))
+ (setcdr help (nconc (if (eq 0 (guided-tour-about-xemacs-index help))
+ (list (cadr help) guided-tour-submenu)
+ (list guided-tour-submenu (cadr help)))
+ (cddr help))))))
+
+;; Is this OK? Don't see how it really hurts.
+;;;###autoload
+(guided-tour-insinuate-menubar)
+
+;; The Guided Tour
+
+(defun guided-tour (type part)
+ "Start the Guided Tour with TYPE viewer, in Part PART."
+ (interactive "sWhich format? \nnWhich part? ")
+ (let ((viewer (symbol-value (intern (concat "guided-tour-" type
"-viewer"))))
+ (file (format "emacs-slides-%d.%s" part type)))
+ (message "\
+`M-x guided-tour-about RET' for FAQ and licensing.")
+ (shell-command (format "%s %s" viewer (or (locate-data-file file)
file)))))
+
+(defun guided-tour-odp-1 ()
+ "Start up the Guided Tour of Emacs, part 1, as an Open Office presentation."
+ (interactive)
+ (guided-tour "odp" 1))
+
+(defun guided-tour-odp-2 ()
+ "Start up the Guided Tour of Emacs, part 2, as an Open Office presentation."
+ (interactive)
+ (guided-tour "odp" 2))
+
+(defun guided-tour-odp-3 ()
+ "Start up the Guided Tour of Emacs, part 3, as an Open Office presentation."
+ (interactive)
+ (guided-tour "odp" 3))
+
+(defun guided-tour-pdf-1 ()
+ "Start up the Guided Tour of Emacs, part 1, in a PDF viewer."
+ (interactive)
+ (guided-tour "pdf" 1))
+
+(defun guided-tour-pdf-2 ()
+ "Start up the Guided Tour of Emacs, part 2, in a PDF viewer."
+ (interactive)
+ (guided-tour "pdf" 2))
+
+(defun guided-tour-pdf-3 ()
+ "Start up the Guided Tour of Emacs, part 3, in a PDF viewer."
+ (interactive)
+ (guided-tour "pdf" 3))
+
+(defun guided-tour-about ()
+ "Document the Guided Tour."
+ (interactive)
+ (with-displaying-temp-buffer "*About the Guided Tour of Emacs*"
+ (princ "\
+
+ A Guided Tour of Emacs
+ Phil Sung
+
+This is the XEmacs package of the Guided Tour of Emacs.
+The slides are by Phil Sung. That's the important part. Send kudos to Phil.
+The XEmacs package is by Stephen Turnbull. Direct complaints about packaging
+to Steve via the XEmacs Developers mailing list <xemacs-beta(a)xemacs.org>.
+The FAQ follows the permissions notice.
+
+Copyright 2007 The Free Software Foundation Inc.
+
+The Guided Tour, is both free software and free content.
+
+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 published by
+the Free Software Foundation.
+
+You can redistribute it and/or modify it under the terms of GNU Free
+Documentation License; either version 1.2, or (at your option) any
+later version published by the Free Software Foundation.
+
+A verbatim or modified version can be redistributed under both
+licenses simultaneously, which is the authors' preferred method.
+
+The Guided Tour 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 and/or the GNU Free Documentation License for more
+details.
+
+FAQ
+
+Q1. I select a tour from the menu, but nothing happens!
+A1. You probably need to configure a viewer. C-h v guided-tour-pdf-viewer RET
+ or C-h v guided-tour-odp-viewer RET.
+"
+
+;; #### Find web, C-h, and maybe file locations for licenses, then add above.
+;; You should have received a copy of the GNU General Public License
+;; along with XEmacs; see the file COPYING. If not, write to the
+;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+;; Boston, MA 02111-1307, USA.
+)))
+
+;;; guided-tour.el ends here
_______________________________________________
XEmacs-Patches mailing list
XEmacs-Patches(a)xemacs.org
http://calypso.tux.org/cgi-bin/mailman/listinfo/xemacs-patches