Here's my attempt at the chapter on how to write backends. Text version
follows, texinfo patch attached.
The predefined backends support commonly used media files and players.
To use other programs with Bongo, you can define your own custom
backends. This involves some Emacs Lisp, but simple non-interactive
backends are easy to define. *Note Emacs Lisp Reference: (elisp)Top,
for help with writing Lisp.
As an example, here is a minimal backend for displaying PostScript
and PDF files with Evince, a GNOME document viewer. We don't need
interactive controls for Evince, we only want to launch it.
(eval-after-load 'bongo
(define-bongo-backend evince
:matcher '(local-file "ps" "pdf")))
`define-bongo-backend' is used to define backends. The definition is
wrapped inside an `eval-after-load' form so that it will execute after
Bongo has loaded. You don't need this if you load Bongo at startup,
but it will work in both cases.
The first argument names the backend. As a side effect, it also
defines the executable file `evince' to be used with the backend. In
most cases, this default behavior is fine. If you want to customize
the invocation of Evince, use `M-x customize-group <RET> bongo-evince
<RET>'. The `define-bongo-backend' macro automatically defines
customizable options for this.
The second argument, the keyword `:matcher', and the third argument
define a matcher for the backend. Files with suffixes `ps' and `pdf'
can now be inserted in Bongo buffers, and Bongo will select the new
backend to display them. The Evince backend is now ready for use.
For information on how to write more advanced backend definitions,
refer to the description of `define-bongo-backend' below. Examples can
be found in `bongo.el'.
-- Macro: define-bongo-backend name [keyword value]...
Defines a new backend named NAME. More specifically, defines
variables used by the backend, a constructor function that will be
invoked to play tracks with the backend and optionally matchers and
translators for the backend. The default definitions can be
overridden with keyword arguments. The NAME argument is not
evaluated.
`define-bongo-backend' accepts the following optional keywords:
`:pretty-name STRING'
The name used to described the backend to the user. The
default is to use NAME.
`:matcher MATCHER'
A backend matcher expression. This keyword can be supplied
multiple times, specifying multiple matchers. There is no
default matcher.
`:file-name-transformer EXPRESSION'
A file name transformer for the backend, to be used by
`bongo-transform-file-name' to manipulate file names. This
keyword can be supplied multiple times, specifying multiple
transformers. There is no default file name transformer.
`:program-name STRING'
The file name of the executable program for the backend. The
default is the symbol-name of NAME.
`:program-name-variable VARIABLE'
The variable specifying the backend executable. The default
defines a variable `bongo-NAME-program-name', bound to the
value of PROGRAM-NAME.
`:program-arguments LIST'
A list of program arguments, to be processed by
`bongo-evaluate-program-arguments'. The default is
`(EXTRA-PROGRAM-ARGUMENTS-VARIABLE bongo-extra-arguments
bongo-file-name)'.
`:extra-program-arguments-variable VARIABLE-NAME'
The name of the variable specifying extra command line
arguments to pass to the program. This variable will be
defined with `defcustom', if its name is mentioned in
EXTRA-PROGRAM-ARGUMENTS. A null value means no variable will
be defined. The default defines a variable
`bongo-NAME-extra-arguments'.
`:extra-program-arguments LIST'
The initial value for the EXTRA-PROGRAM-ARGUMENTS-VARIABLE
variable. The default is `nil'.
`:constructor FUNCTION'
The function that will create and invoke the backend player.
It must be a function of two arguments, a file name and a
list of extra arguments. It shall return a player,
represented by a cons `(name . properties)' where
`properties' is an alist.
The default defines a function `bongo-start-NAME-player'
which calls `bongo-start-simple-player'.
`:pause-signal SIGCODE'
The signal used with `signal-process' to pause the player
process. The default is `SIGSTOP'.
diff -Naur bongo-old/bongo.texinfo bongo-new/bongo.texinfo
--- bongo-old/bongo.texinfo 2007-05-27 18:38:54.000000000 +0200
+++ bongo-new/bongo.texinfo 2007-06-01 20:28:53.000000000 +0200
@@ -8,6 +8,7 @@
@copying
Copyright @copyright{} 2007 Daniel Brockman
+Copyright @copyright{} 2007 Daniel Jensen
@quotation
Permission is granted to copy, distribute and/or modify this document
@@ -580,6 +581,110 @@
@node Writing Backends
@chapter Writing Backends
+The predefined backends support commonly used media files and players.
+To use other programs with Bongo, you can define your own custom
+backends. This involves some Emacs Lisp, but simple non-interactive
+backends are easy to define. @xref{Top, Emacs Lisp Reference,, elisp,
+GNU Emacs Lisp Reference Manual}, for help with writing Lisp.
+
+As an example, here is a minimal backend for displaying PostScript and
+PDF files with Evince, a GNOME document viewer. We don't need
+interactive controls for Evince, we only want to launch it.
+
[EMAIL PROTECTED]
+(eval-after-load 'bongo
+ (define-bongo-backend evince
+ :matcher '(local-file "ps" "pdf")))
[EMAIL PROTECTED] lisp
+
[EMAIL PROTECTED] is used to define backends. The definition
+is wrapped inside an @code{eval-after-load} form so that it will
+execute after Bongo has loaded. You don't need this if you load Bongo
+at startup, but it will work in both cases.
+
+The first argument names the backend. As a side effect, it also
+defines the executable file @file{evince} to be used with the backend.
+In most cases, this default behavior is fine. If you want to
+customize the invocation of Evince, use @kbd{M-x customize-group
[EMAIL PROTECTED] bongo-evince @key{RET}}. The @code{define-bongo-backend}
+macro automatically defines customizable options for this.
+
+The second argument, the keyword @code{:matcher}, and the third
+argument define a matcher for the backend. Files with suffixes
[EMAIL PROTECTED] and @file{pdf} can now be inserted in Bongo buffers, and
+Bongo will select the new backend to display them. The Evince backend
+is now ready for use.
+
+For information on how to write more advanced backend definitions,
+refer to the description of @code{define-bongo-backend} below.
+Examples can be found in @file{bongo.el}.
+
[EMAIL PROTECTED] define-bongo-backend name [keyword [EMAIL PROTECTED]
+Defines a new backend named @var{name}. More specifically, defines
+variables used by the backend, a constructor function that will be
+invoked to play tracks with the backend and optionally matchers and
+translators for the backend. The default definitions can be
+overridden with keyword arguments. The @var{name} argument is not
+evaluated.
+
[EMAIL PROTECTED] accepts the following optional keywords:
+
[EMAIL PROTECTED] @code
[EMAIL PROTECTED] :pretty-name @var{string}
+The name used to described the backend to the user. The default is to
+use @var{name}.
+
[EMAIL PROTECTED] :matcher @var{matcher}
+A backend matcher expression. This keyword can be supplied multiple
+times, specifying multiple matchers. There is no default matcher.
+
[EMAIL PROTECTED] :file-name-transformer @var{expression}
+A file name transformer for the backend, to be used by
[EMAIL PROTECTED] to manipulate file names. This
+keyword can be supplied multiple times, specifying multiple
+transformers. There is no default file name transformer.
+
[EMAIL PROTECTED] :program-name @var{string}
+The file name of the executable program for the backend. The default
+is the symbol-name of @var{name}.
+
[EMAIL PROTECTED] :program-name-variable @var{variable}
+The variable specifying the backend executable. The default defines a
+variable @[EMAIL PROTECTED], bound to the value of
[EMAIL PROTECTED]
+
[EMAIL PROTECTED] :program-arguments @var{list}
+A list of program arguments, to be processed by
[EMAIL PROTECTED] The default is
[EMAIL PROTECTED](@var{extra-program-arguments-variable} bongo-extra-arguments
+bongo-file-name)}.
+
[EMAIL PROTECTED] :extra-program-arguments-variable @var{variable-name}
+The name of the variable specifying extra command line arguments to
+pass to the program. This variable will be defined with
[EMAIL PROTECTED], if its name is mentioned in
[EMAIL PROTECTED] A null value means no variable will be
+defined. The default defines a variable
[EMAIL PROTECTED]@var{name}-extra-arguments}.
+
[EMAIL PROTECTED] :extra-program-arguments @var{list}
+The initial value for the @var{extra-program-arguments-variable}
+variable. The default is @code{nil}.
+
[EMAIL PROTECTED] :constructor @var{function}
+The function that will create and invoke the backend player. It must
+be a function of two arguments, a file name and a list of extra
+arguments. It shall return a player, represented by a cons
[EMAIL PROTECTED](name . properties)} where @code{properties} is an alist.
+
+The default defines a function @[EMAIL PROTECTED]
+which calls @code{bongo-start-simple-player}.
+
[EMAIL PROTECTED] :pause-signal @var{sigcode}
+The signal used with @code{signal-process} to pause the player
+process. The default is @code{SIGSTOP}.
[EMAIL PROTECTED] table
[EMAIL PROTECTED] defmac
@node GNU GPL
@appendix GNU General Public License
_______________________________________________
bongo-devel mailing list
[email protected]
http://lists.nongnu.org/mailman/listinfo/bongo-devel
