cgit.sxemacs.org Git - packages/blob - xemacs-packages/guided-tour/guided-tour.el

   1 ;;; guided-tour.el --- functions for viewing Phil Sung's Emacs Guided Tour
   2
   3 ;; Copyright 2007, 2008 Free Software Foundation, Inc.
   4
   5 ;; Author: Stephen J. Turnbull <stephen@xemacs.org>
   6 ;; Maintainer: XEmacs Development Team
   7 ;; Created: 2007-05-02
   8 ;; Last-Modified: 2008-03-19
   9 ;; Keywords: doc
  10
  11 ;; The permissions notice is contained in the function `guided-tour-about'
  12 ;; at the end of this file.  Under the terms granted, you may modify that
  13 ;; function, but the appropriate permissions notice must remain somewhere in
  14 ;; any file derived from this one.
  15
  16 ;;; Synched up with: Not in FSF.
  17
  18 ;;; Commentary:
  19
  20 ;; Thanks to Jason Spiro and Phil Sung for making substantial effort
  21 ;; to make this content as useful to XEmacs as possible.
  22
  23 ;;; Code:
  24
  25 ;; Variables
  26
  27 (defgroup guided-tour nil "The Guided Tour of Emacs")
  28
  29 ;; #### this belongs somewhere more generic
  30 ;; #### it would be nice to be able to filter it for platform
  31 ;; #### The docstrings don't appear in the Value Menu.  Tried the menu-choice
  32 ;; widget and the :tag and :menu-tag keywords in various combinations, no joy.
  33 (defcustom guided-tour-open-utilities
  34   '((const "open" :doc "Useful on Mac OS X")
  35     (const "xdg-open" :doc "Freedesktop `open' utility.")
  36     (const "see" :doc "Open source `open' utility")
  37     (const "gnome-open" :doc "GNOME `open' utility - some report it doesn't work"))
  38   "List of generic \"open document\" command-line utilities.
  39 Each utility should be able to determine the right application to use to open
  40 an arbitrary file passed to it on the command line.")
  41
  42 (defcustom guided-tour-odp-viewer "ooimpress"
  43   "Path to program able to view Open Document Format presentations.
  44 Program is invoked in a shell, so PATH is searched."
  45   :type (append '(choice string
  46                   (const "ooimpress"))
  47                 guided-tour-open-utilities)
  48   :group 'guided-tour)
  49
  50 (defcustom guided-tour-pdf-viewer "xpdf"
  51   "Path to program able to view Portable Document Format documents.
  52 Program is invoked in a shell, so PATH is searched."
  53   :type (append '(choice string
  54                   (const "xpdf")
  55                   (const "gv"))
  56                 guided-tour-open-utilities)
  57   :group 'guided-tour)
  58
  59 (defconst guided-tour-submenu
  60   '("A Guided Tour of Emacs"
  61     ["Guided Tour, Part %_1 (OOo)" guided-tour-odp-1]
  62     ["Guided Tour, Part %_2 (OOo)" guided-tour-odp-2]
  63     ["Guided Tour, Part %_3 (OOo)" guided-tour-odp-3]
  64     ["Guided Tour, Part %_1 (PDF)" guided-tour-pdf-1]
  65     ["Guided Tour, Part %_2 (PDF)" guided-tour-pdf-2]
  66     ["Guided Tour, Part %_3 (PDF)" guided-tour-pdf-3]
  67     ["About COPYING the Tour" guided-tour-about])
  68   "The submenu for the \"Guided Tour of Emacs\".")
  69
  70 (defvar guided-tour-insinuate-menubar load-user-init-file-p
  71   "If nil, the function `guided-tour-insinuate-menubar' exits immediately.
  72 Guards against multiple insinuations of the menu into the menubar.
  73 Note that if you make this t and reinsinuate, you are responsible for
  74 removing any existing instances of the submenu.")
  75
  76 ;; Functions
  77
  78 ;; Helper functions
  79
  80 ;; #### this probably should move to help.el or menubar-items.el
  81 (defun guided-tour-find-menubar-help-menu (&optional menubar)
  82   "Return the Help submenu for MENUBAR if present, else nil."
  83   (assoc "%_Help" (or menubar default-menubar)))
  84
  85 (defun guided-tour-about-xemacs-index (menu)
  86   "Return the (zero-based) index of the About XEmacs item in MENU.
  87 Returns nil if not present."
  88   ;; #### Of course we should actually search for it....
  89   ;; Does easy-menu provide functions for this?  It should....
  90   (let ((item (cadr menu)))
  91     (if (and (vectorp item) (eq 'about-xemacs (aref item 1)))
  92         0
  93       nil)))
  94
  95 ;; Initialization
  96
  97 ;;;###autoload
  98 (defun guided-tour-insinuate-menubar ()
  99   "Add the Guided Tour of Emacs to the default menubar.
 100 This is normally done at startup if the user's init file was loaded.
 101 To inhibit, set `guided-tour-insinuate-menubar' to nil in your init file.
 102 If called interactively, insinuates menubar unconditionally \(warning:
 103 that means even if the Guided Tour item is already present)."
 104   (interactive)
 105   (when (or guided-tour-insinuate-menubar (interactive-p))
 106     (setq guided-tour-insinuate-menubar nil)
 107     (let* ((help (guided-tour-find-menubar-help-menu)))
 108       (setcdr help (nconc (if (eq 0 (guided-tour-about-xemacs-index help))
 109                               (list (cadr help) guided-tour-submenu)
 110                             (list guided-tour-submenu (cadr help)))
 111                           (cddr help))))))
 112
 113 ;; Is this OK?  Don't see how it really hurts.
 114 ;;;###autoload
 115 (add-one-shot-hook 'after-init-hook #'guided-tour-insinuate-menubar)
 116
 117 ;; The Guided Tour
 118
 119 ;;;###autoload
 120 (defun guided-tour (type part)
 121   "Start the Guided Tour with TYPE viewer, in Part PART."
 122   (interactive "sWhich format? \nnWhich part? ")
 123   (let ((viewer (symbol-value (intern (concat "guided-tour-" type "-viewer"))))
 124         (file (format "emacs-slides-%d.%s" part type)))
 125     (message "\
 126 `M-x guided-tour-about RET' for FAQ and licensing.")
 127     (shell-command (format "%s %s" viewer (or (locate-data-file file) file)))))
 128
 129 (defun guided-tour-odp-1 ()
 130   "Start up the Guided Tour of Emacs, part 1, as an Open Office presentation."
 131   (interactive)
 132   (guided-tour "odp" 1))
 133
 134 (defun guided-tour-odp-2 ()
 135   "Start up the Guided Tour of Emacs, part 2, as an Open Office presentation."
 136   (interactive)
 137   (guided-tour "odp" 2))
 138
 139 (defun guided-tour-odp-3 ()
 140   "Start up the Guided Tour of Emacs, part 3, as an Open Office presentation."
 141   (interactive)
 142   (guided-tour "odp" 3))
 143
 144 (defun guided-tour-pdf-1 ()
 145   "Start up the Guided Tour of Emacs, part 1, in a PDF viewer."
 146   (interactive)
 147   (guided-tour "pdf" 1))
 148
 149 (defun guided-tour-pdf-2 ()
 150   "Start up the Guided Tour of Emacs, part 2, in a PDF viewer."
 151   (interactive)
 152   (guided-tour "pdf" 2))
 153
 154 (defun guided-tour-pdf-3 ()
 155   "Start up the Guided Tour of Emacs, part 3, in a PDF viewer."
 156   (interactive)
 157   (guided-tour "pdf" 3))
 158
 159 (defun guided-tour-about ()
 160   "Document the Guided Tour."
 161   (interactive)
 162   ;; for 21.4 compatibility
 163   (with-displaying-help-buffer (lambda () (princ "\
 164
 165                         A Guided Tour of Emacs
 166                               Phil Sung
 167
 168 This is the XEmacs package of the Guided Tour of Emacs.
 169 The slides are by Phil Sung.  That's the important part.  Send kudos to Phil.
 170 The XEmacs package is by Stephen Turnbull.  Direct complaints about packaging
 171 to Steve via the XEmacs Developers mailing list <xemacs-beta@xemacs.org>.
 172 The FAQ follows the permissions notice.
 173
 174 Copyright 2007, 2008 The Free Software Foundation Inc.
 175
 176 The Guided Tour is both free software and free content.
 177
 178 You can redistribute it and/or modify it under the terms of the GNU
 179 General Public License as published by the Free Software Foundation;
 180 either version 2, or (at your option) any later version published by
 181 the Free Software Foundation.
 182
 183 You can redistribute it and/or modify it under the terms of GNU Free
 184 Documentation License; either version 1.2, or (at your option) any
 185 later version published by the Free Software Foundation.
 186
 187 A verbatim or modified version can be redistributed under both
 188 licenses simultaneously, which is the authors' preferred method.
 189
 190 The Guided Tour is distributed in the hope that it will be useful, but
 191 WITHOUT ANY WARRANTY; without even the implied warranty of
 192 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 193 General Public License and/or the GNU Free Documentation License for more
 194 details.
 195
 196 FAQ
 197
 198 Section 1: Problems
 199
 200 Q1.1  I select a tour from the menu, but nothing happens!
 201 A1.1  You probably need to configure a viewer.  C-h v guided-tour-pdf-viewer RET
 202       or C-h v guided-tour-odp-viewer RET.
 203
 204 Section 2: Further Info.
 205
 206 Q2.1  Where can I find the licenses?
 207 A2.1  The GPL is included with XEmacs and Emacs, and the GFDL is included with
 208       several XEmacs packages and Emacs.  You can also visit the GNU home page
 209       at http://www.gnu.org/licenses/ where the GPL and GFDL (as well as the
 210       Library/Lesser GPL) are available for browsing.  Finally, you can write
 211       to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 212       Boston, MA 02111-1307, USA, and request a copy.
 213
 214 Q2.2  Are there updated versions?
 215 A2.2  Perhaps.  See Phil's Emacs page at http://stuff.mit.edu/iap/emacs/ and/or
 216       http://www.gnu.org/software/emacs/tour/.
 217
 218 Q2.3  Can I see an HTML version?
 219 A2.3  Yes, at Phil's site and at gnu.org (see A2.1).
 220
 221 Q2.4  Will an HTML version be included in the future?
 222 A2.4  Patches welcome!  Ask about how to contribute to the XEmacs package, or
 223       lobby for inclusion of new/updated content at <xemacs-beta@xemacs.org>.
 224 ")
 225                                  "*About the Guided Tour of Emacs*")))
 226
 227 (provide 'guided-tour)
 228
 229 ;;; guided-tour.el ends here