updated v1.3 Emacs menu

Michael Smith <[email protected]> Tue, 9 Dec 2003 00:07:49 +0900

Newsgroups	gmane.text.refdb.devel
Message-ID	<20031208150731.GA1556@theThirdPoliceman>

Attached is an updated version of the RefDB menu for Emacs.

This includes only a couple changes:

  - added logic for optionally automatically setting the input type to
    RISX if you're in a major mode whose name contains "xml" or "sgml",
    and a new variable, refdb-menu-input-type-risx for controlling that

  - added a "Select Output Type" submenu, and a new variable,
    refdb-menu-output-type, for setting the default output type

The refdb-menu-input-type-risx variable works like this:

  - if t, always use RISX, regardless of mode
  - if nil, never use RISX, regardless of mode
  - if non-t & non-nil, use RISX if in an "xml" or "sgml" mode (default)

Note about setting the refdb-menu-output-type variable: If you set a
value for it manually in your .emacs, set it like this:

  (setq refdb-menu-output-type 'db31x)

That is, make the value a quoted symbol, not a string. The reason I set
it up that way is that it makes it easier to customize via the built-in
Emacs customization interface. To see what I mean:

  1. Do M-x customize-variable refdb-menu-output-type.

  2. Click the "Value Menu" widget.
     It should show you a list of selectable values, like this:

       Screen
       HTML
       XHTML
       DocBook SGML
       DocBook XML
       TEI XML
       BibTeX
       RIS
       RISX

     That'll allow users to just choose an output type based on the
     is descriptive name, rather than needing to know or care that,
     e.g., "scrn" means "Screen" or "db31" means "DocBook SGML".

I also got a couple of Postgres-based RefDB installs successfully set up
over the weekend (Debian unstable and Cygwin). I've got some test data
from Markus to work with, so next step is I'll try to add that to the
database using via Emacs using the RefDB menu; if that works, I'll have
a couple of environments I can do some real testing with.

So please let me know what the priorities should be for features to
added to the menu next.

I should be able to get started on trying out some of the things we've
already discussed -- like dynamically auto-populating the Select
Database submenu based on a listdb query at startup, and dynamically
generating completion lists for authors/titles, etc. -- but if anybody
has other ideas, please let me know.

I still don't have a totally clear idea of how to proceed with the 
document creation / bibliography / document processing side of things. I
think there's a lot of potential for putting an easy-to-use front-end on
it equivalent to what users can do with running refdbnd and the
makefiles from the command line. Based on my limited understanding from
a quick look at the docs, here's a rough guess at how it could work:

  1. Add a "Create New Document..." menu item.

     Selecting that will fire up refdbnd (or some Emacs-based equivalent
     of that) and create the makefile for the document at the same
     time as the document is created.

  2. Add a "Process Document" or "Generate Output" submenu, with "PDF",
     "HTML",  "RTF" and "All" menu items.

     Selecting that will just call up the corresponding makefile for the
     document, and pass it the appropriate target name.

It seems like the "Process Document" submenu will either need to work
from the assumption that there's only one document per directory, and
it's associated with a file called "Makefile" in the same directory. Or
it could work by looking for a file with the extension ".mk" and the
same base name as the document in the current buffer. That'd allow you
to have multiple documents in the same directory.

Anyway, just some ideas. Let me know what you all think.

  --Mike

refdb-menu.el (text/plain, 17.7 KB)

;;; refdb-menu.el --- Menu for RefDB interaction
;; $Id: refdb-menu.el,v 1.3 2003/12/08 15:06:46 xmldoc Exp $

;; Copyright (C) 2003 Michael Smith

;; Author: Michael Smith <[email protected]>
;; Maintainer: Michael Smith <[email protected]>
;; Created: 2003-11-04
;; Version: 0.90
;; Revision: $Revision: 1.3 $
;; Date: $Date: 2003/12/08 15:06:46 $
;; RCS Id: $Id: refdb-menu.el,v 1.3 2003/12/08 15:06:46 xmldoc Exp $
;; X-URL: http://refdb.sf.net/
;; Keywords: xml docbook tei bibliography

;; This file is NOT 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 software 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.

;; -------------------------------------------------------------------
;;; Compatibility
;; -------------------------------------------------------------------
;; 
;; -------------------------------------------------------------------
;;; Commentary
;;-------------------------------------------------------------------
;; This package adds a customizable RefDB menu to your menu bar.
;;
;; See the Details section below for details about the menu contents.
;;
;; -------------------------------------------------------------------
;;; Installation and Configuration
;; -------------------------------------------------------------------
;;
;; To install and use this package:
;;
;; 1. Either put this file into a directory that's already in your
;;    load path, or add whatever directory it's already in to your
;;    load path.  For example,
;;
;;      (add-to-list 'load-path "c:/my-xml-stuff/elisp/")
;;
;; 2. Add the following to the end of your .emacs file exactly as
;;    shown:
;;
;;      (require 'refdb-menu)
;;
;; 3. You should probably specify a database that will be used by
;;    default.  You can do that by adding the following to your .emacs,
;;    with DATABASE replaced by the name of the database to use.
;;
;;      (setq refdb-menu-database "DATABASE")
;;
;; After you restart Emacs, to view the menu at any time, either:
;;
;;   - choose Show RefDB Menu from the Emacs Help menu
;;       or
;;   - type "¥M-x refdb-menu-mode<return>" (on MS Windows, that's
;;     "Alt-x refdb-menu-mode" and then hit <Enter>)
;;
;; Showing the menu automatically
;; ------------------------------
;; There are a couple of ways you can make the menu automatically
;; show up (rather than needing to invoke it manually)
;; 
;;   - To show the menu by default, after you open a new file, so that
;;     it shows up no matter what buffer/mode you're in, add the
;;     following to your .emacs file:
;;
;;       (add-hook 'find-file-hooks 'refdb-menu-mode)
;;
;;   - To show the menu only when you're in a certain major mode (for
;;     example, only in nxml-mode)
;;
;;       (add-hook 'nxml-mode-hook 'refdb-menu-mode)
;;
;; To be able to show/hide the menu using a shorter keyboard shortcut,
;; you need to add something like the following to your .emacs file.
;;
;;   (define-key global-map "¥C-cb" 'refdb-menu-mode)
;;
;; That example will enable you to use the 'Ctrl-c b' keyboard to
;; show/hide the menu.
;;
;; -------------------------------------------------------------------
;;; Customization
;; -------------------------------------------------------------------
;; To customize the menu contents and behavior, either:
;;
;;   - choose Customize RefDB Menu from the menu itself
;;       or
;;   - type ¥M-x customize-group<return>refdb-menu<return>
;;
;; -------------------------------------------------------------------
;;; Details
;; -------------------------------------------------------------------
;; By default, `refdb-menu-mode' provides the following submenus:
;;
;;   Add Reference
;;   Search
;;   Select Output Type
;;   List All Databases
;;   List Matching Databases
;;   Select Database
;;   ----
;;   Customize RefDB Menu
;;
;; Here are brief descriptions of each submenu:
;;
;;   Add Reference
;;     Runs 'refdbc -C addref' on the current region.
;;
;;   Search
;;     Provides submenus for passing various queries to
;;     'refdbc -C getref'.
;;
;;   Select Output Type
;;     Select the output type passed as an argument to the -t option
;;     for the 'refdbc -C getref' command when performing queries.
;;
;;   List All Databases
;;     Runs 'refdbc -C listdb' with no argument.
;;
;;   List Matching Databases
;;     Prompts for a pattern and passes that as an argument to
;;     'refdbc -C listdb'
;;
;;   Select Database
;;     Allows you to change the database name passed via the -d option
;;     to RefDB programs.
;;
;;   Customize RefDB Menu
;;     User-friendly interface for setting options and
;;     adding/removing/rearranging submenus.
;; 
;; -------------------------------------------------------------------
;;; Bugs
;; -------------------------------------------------------------------
;; Probably.  Still needs more testing.  Reports of a possibly
;; reproducible crash with OS X (Panther)
;;
;; -------------------------------------------------------------------
;;; History:
;; -------------------------------------------------------------------
;;   2003-12-nn - first public release
;;
;; -------------------------------------------------------------------
;;; Acknowledgments
;; -------------------------------------------------------------------
;;

;;; Code:

;; *******************************************************************
;;; Initialization
;; *******************************************************************

(require 'easymenu)
(require 'easy-mmode)

(defvar refdb-menu-addref-menu-item
  ["Add Reference" (refdb-menu-addref) t]
  "RefDB menu item for adding references."
  )

(defvar refdb-menu-search-by-author-menu-item
  ["Author..." (list
	     (setq refdb-menu-current-prompt "Author")
	     (setq refdb-menu-current-field "AU")
	     (call-interactively 'refdb-menu-getref-by-field)
	     )
   t]
  "RefDB search-by-author menu item."
  )

(defvar refdb-menu-search-by-title-menu-item
  ["Title..." (list
	     (setq refdb-menu-current-prompt "Title")
	     (setq refdb-menu-current-field "TI")
	     (call-interactively 'refdb-menu-getref-by-field)
	     )
   t]
  "RefDB search-by-title menu item."
  )

(defvar refdb-menu-search-by-keyword-menu-item
  ["Keyword..." (list
	     (setq refdb-menu-current-prompt "Keyword")
	     (setq refdb-menu-current-field "KW")
	     (call-interactively 'refdb-menu-getref-by-field)
	     )
   t]
  "RefDB search-by-keyword menu item."
  )

(defvar refdb-menu-search-by-id-menu-item
  ["ID..." (list
	     (setq refdb-menu-current-prompt "ID")
	     (setq refdb-menu-current-field "ID")
	     (call-interactively 'refdb-menu-getref-by-field)
	     )
   t]
  "RefDB search-by-id menu item."
  )

(defvar refdb-menu-search-by-citekey-menu-item
  ["Citation Key..." (list
	     (setq refdb-menu-current-prompt "Citation Key")
	     (setq refdb-menu-current-field "CK")
	     (call-interactively 'refdb-menu-getref-by-field)
	     )
   t]
  "RefDB search-by-citation-key menu item."
  )

(defvar refdb-menu-search-by-advanced-search-menu-item
  ["Advanced Search..."
   (call-interactively 'refdb-menu-getref-by-advanced-search)
   t]
  "RefDB advanced-search menu item."
  )

(defvar refdb-menu-output-type-submenu-contents
  (list "Select Output Type"
	["Screen"        (setq refdb-menu-output-type "scrn")   t]
	["HTML"          (setq refdb-menu-output-type "html")   t]
	["XHTML"         (setq refdb-menu-output-type "xhtml")  t]
	["DocBook SGML"  (setq refdb-menu-output-type "db31")   t]
	["DocBook XML"   (setq refdb-menu-output-type "db31x")  t]
	["TEI XML"       (setq refdb-menu-output-type "teix")   t]
	["BibTeX"        (setq refdb-menu-output-type "bibtex") t]
	["RIS"           (setq refdb-menu-output-type "ris")    t]
	["RISX"          (setq refdb-menu-output-type "risx")   t]
	)
  "RefDB select-output-type submenu."
  )

(defvar refdb-menu-listdb-all-menu-item
  ["List All Databases"
   (refdb-menu-listdb-all-command)
   t]
  "RefDB menu item for listing all databases."
  )

(defvar refdb-menu-listdb-matching-menu-item
  ["List Matching Databases..."
   (call-interactively 'refdb-menu-listdb-matching-command)
   t]
  "RefDB menu item for listing DBs matching a certain pattern."
  )

(defvar refdb-menu-selectdb-menu-item
  ["Select Database..."
   (call-interactively 'refdb-menu-selectdb)
   t]
  "RefDB menu item for selecting a database as the current database."
  )

(defun refdb-menu-addref ()
  "Add references in the current region to the current RefDB database."
  (interactive)
  (if (not (eq (length refdb-menu-database) 0))
      (if (mark)
	  (shell-command-on-region
	   (point) (mark)
	   (format
	    "%s -d %s -t %s -C addref"
	    refdb-menu-refdbc-program-and-options
	    refdb-menu-database
	    ;; check to see what value for input type should be
	    (if (and refdb-menu-input-type-risx
		     (not (eq refdb-menu-input-type-risx t)))
		;; unless user has specified that input type should
		;; never be RISX, or specified that input type should
		;; always be RISX, check to see what the name of the
		;; major mode is, and if the major mode name contains
		;; 'xml' or 'sgml', set the input type to
		;; RISX. Otherwise, set the input type to RIS
		(if
		    (not (null
			  (string-match
			   "sgml¥¥|xml"
			   (downcase (symbol-name major-mode)))))
		    (quote "risx")
		  (quote "ris")
		  )
	      (quote "ris")
	      )
	    "*refdbc-output*" nil)
	   )
	(message "Error: No region marked.
	      You must mark a region containing references to add.")
	)
    (message "Error: No database specified.
	      You must either select a database using the RefDB > Select Database
	      menu, or set a value for the refdb-menu-database option.")
    )
  )

(defun refdb-menu-getref-by-field (value)
  "Display all RefDB datasets that match the specified field and VALUE."
  (interactive (list (read-string (format "%s: " refdb-menu-current-prompt))))
  (if (not (eq (length refdb-menu-database) 0))
      (shell-command
       (format
	"%s -d %s -C getref :%s:=%s"
	refdb-menu-refdbc-program-and-options
	refdb-menu-database
	refdb-menu-current-field
	value)
       "*refdbc-output*" nil)
    (message "Error: No database specified.
	      You must either select a database using the RefDB > Select Database
menu, or set a value for the refdb-menu-database option.")
    )
  )

(defun refdb-menu-getref-by-advanced-search (searchstring)
  "Display all RefDB datasets that match the SEARCHSTRING."
  (interactive "sSearch string: ")
  (if (not (eq (length refdb-menu-database) 0))
      (shell-command
       (point) (mark)
       (format
	"%s -d %s -t %s -C getref %s"
	refdb-menu-refdbc-program-and-options
	refdb-menu-database
	(symbol-name refdb-menu-output-type)
	searchstring)
       "*refdbc-output*" nil)
    (message "Error: No database specified.
You must either select a database using the RefDB > Select Database
menu, or set a value for the refdb-menu-database option.")
    )
  )

(defun refdb-menu-listdb-all-command ()
  "List all available RefDB databases."
  (shell-command
  (format "%s -d %s -C listdb"
	  refdb-menu-refdbc-program-and-options
	  refdb-menu-database
	  )
   "*refdbc-output*" nil)
  )

(defun refdb-menu-listdb-matching-command (pattern)
  "List RefDB databases matching PATTERN."
  (interactive "sPattern: ")
  (shell-command
  (format "%s %s -C listdb %s"
	  refdb-menu-refdbc-program-and-options
	  refdb-menu-database
	  pattern
	  )
   "*refdbc-output*" nil)
  )

(defun refdb-menu-selectdb (database)
  "Select DATABASE as the current RefDB database."
  (interactive "sDatabase: ")
  (setq refdb-menu-database database)
  )

(easy-mmode-define-minor-mode refdb-menu-mode
  "Minor mode that displays a menu for RefDB interaction."
  ;; Initial value is nil.
  nil
  ;; No indicator for the mode line.
  nil
  ;; Make empty default keymap;
  '( ("" . nil)))

(defvar refdb-menu-item-separator1
  ["--" t]
  "Separator between command `refdb-menu-mode' menu items."
  )
(defvar refdb-menu-item-separator2
  ["---" t]
  "Separator between command `refdb-menu-mode' menu items."
  )
(defvar refdb-menu-item-separator3
  ["----" t]
  "Separator between command `refdb-menu-mode' menu items."
  )
(defvar refdb-menu-item-separator4
  ["-----" t]
  "Separator between command `refdb-menu-mode' menu items."
  )

(defvar refdb-menu-customize
  ["Customize RefDB Menu..."
   (customize-group 'refdb-menu) t]
  "Customize submenu for command `refdb-menu-mode'."
  )

(defgroup refdb-menu nil
  "RefDB menu."
  :group 'help
  :link '(emacs-commentary-link "refdb-menu.el")
  :link '(url-link "http://refdb.sf.net/")
  :prefix "refdb-menu-"
  )

;; *******************************************************************
;;; User-customizable options
;; *******************************************************************

(defcustom refdb-menu-database ""
  "*Name of a RefDB database to use in RefDB commands.
Passed to RefDB commands as the parameter for the -d option."
  :type 'string
  :group 'refdb-menu
  )

(defcustom refdb-menu-input-type-risx 'use-mode-name
  "*Indicates whether RISX is used as the input type.
Passed to the 'refdbc -C addref' command as the argument for the -t
option.  If t, RISX is always used.  If nil, RISX is never used.  If
non-t and non-nil, use RISX if the name of the buffer's major mode
contains 'xml' or 'sgml'."
  :type '(choice (const :tag "always" t) (const :tag "never" nil)
		 (const :tag "use-mode-name" use-mode-name))
  :group 'refdb-menu
)

(defcustom refdb-menu-output-type 'scrn
  "*Specifies the default output type.
Passed to the 'refdbc -C getref' command as the argument for the -t
option."

  :type '(choice (const :tag "Screen"        scrn)
		 (const :tag "HTML  "        html)
		 (const :tag "XHTML  "       xhtml)
		 (const :tag "DocBook SGML"  db31)
		 (const :tag "DocBook XML "  db31x)
		 (const :tag "TEX XML     "  teix)
		 (const :tag "BibTeX      "  bibtex)
		 (const :tag "RIS         "  ris)
		 (const :tag "RISX        "  risx)
		 )
  :group 'refdb-menu
)

(defcustom refdb-menu-refdbc-program "refdbc"
  "File name of the refdbc executable."
  :type 'string
  :group 'refdb-menu)

(defcustom refdb-menu-refdbc-options ""
  "RefDB global options; always included, regardless of subcommand."
  :set-after '(refdb-menu-database-default)
  :type 'string
  :group 'refdb-menu)

(defcustom refdb-menu-refdbc-addref-options (format "")
  "RefDB options to include whenever the addref command is called."
  :type 'string
  :group 'refdb-menu)

(defcustom refdb-menu-refdbc-getref-options (format "")
  "RefDB options to include whenever the getref command is called."
  :type 'string
  :group 'refdb-menu)

(defcustom refdb-menu-refdbc-program-and-options
  (format "%s %s"
	  refdb-menu-refdbc-program
	  refdb-menu-refdbc-options
	  )
  "RefDB command along with global options."
  :type 'string
  :group 'refdb-menu)

(defcustom refdb-menu-getref-submenu-contents
  '(
   refdb-menu-search-by-author-menu-item
   refdb-menu-search-by-title-menu-item
   refdb-menu-search-by-keyword-menu-item
   refdb-menu-search-by-id-menu-item
   refdb-menu-search-by-citekey-menu-item
   refdb-menu-search-by-advanced-search-menu-item
   )
  "*Contents of 'Search' submenu for the command `refdb-menu-mode' menu.
Customize this to add/remove/rearrange submenus."
  :set (lambda (sym val)
         (setq refdb-menu-getref-submenu-contents val)
	 (setq refdb-menu-getref-submenu-definition
	       (cons "Search"
		     ;; turn quoted refdb-menu-contents value back into a real list
		     ;; thanks, sachac :)
		     (mapcar (lambda (item) (if (symbolp item) (eval item) item)) val)
		     )
	       )
	 )
  :group 'refdb-menu
  :type '(repeat variable)
  )

(defcustom refdb-menu-contents
  '(
   refdb-menu-addref-menu-item
   refdb-menu-getref-submenu-definition
   refdb-menu-output-type-submenu-contents
   refdb-menu-listdb-all-menu-item
   refdb-menu-listdb-matching-menu-item
   refdb-menu-selectdb-menu-item
   refdb-menu-item-separator4
   refdb-menu-customize
   )
  "*Contents of command `refdb-menu-mode' menu.
Customize this to add/remove/rearrange submenus."
  :set (lambda (sym val)
         (setq refdb-menu-contents val)
	 (setq refdb-menu-definition
	       (cons "RefDB"
		     (mapcar (lambda (item) (if (symbolp item) (eval item) item)) val)
		     )
	       )
	 )
  :group 'refdb-menu
  :type '(repeat variable)
  )

(defcustom refdb-menu-suppress-from-help-menu-flag nil
  "*Non-nil means suppress 'Show RefDB Menu' from Help menu.
Set to non-nil ¥(on¥) to suppress, leave at nil ¥(off¥) to show."
  :type 'boolean
  :group 'refdb-menu
  :require 'refdb-menu
  )

;; *******************************************************************
;; end of user-customizable options
;; *******************************************************************

(add-hook 'refdb-menu-mode-hook
	  ;;create the actual RefDB menu using easy-menu
	  '(lambda ()
	     (easy-menu-define
	       refdb-menu-menu
	       refdb-menu-mode-map
	       "Easy menu command/variable for `refdb-menu-mode'."
	       refdb-menu-definition)
	     )
	  )

(define-key-after menu-bar-help-menu [refdb-menu-show]
  ;; add "Show RefDB Menu" item to Help menu
  '(menu-item "Show RefDB Menu" refdb-menu-mode
	      :help "Toggle display of RefDB Menu"
	      :button (:toggle . (and (boundp 'refdb-menu-mode) refdb-menu-mode))
	      ;; hide if 'suppress' flag is set
	      :visible (not refdb-menu-suppress-from-help-menu-flag)
	      )
  nil)

(provide 'refdb-menu)

;;; refdb-menu.el ends here