[bongo-devel] Writing Backends manual node

[Daniel Jensen]

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.
+
address@hidden
+(eval-after-load 'bongo
+  (define-bongo-backend evince
+    :matcher '(local-file "ps" "pdf")))
address@hidden lisp
+
address@hidden 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
address@hidden 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
address@hidden 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}.
+
address@hidden define-bongo-backend name [keyword address@hidden
+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.
+
address@hidden accepts the following optional keywords:
+
address@hidden @code
address@hidden :pretty-name @var{string}
+The name used to described the backend to the user.  The default is to
+use @var{name}.
+
address@hidden :matcher @var{matcher}
+A backend matcher expression.  This keyword can be supplied multiple
+times, specifying multiple matchers.  There is no default matcher.
+
address@hidden :file-name-transformer @var{expression}
+A file name transformer for the backend, to be used by
address@hidden to manipulate file names.  This
+keyword can be supplied multiple times, specifying multiple
+transformers.  There is no default file name transformer.
+
address@hidden :program-name @var{string}
+The file name of the executable program for the backend.  The default
+is the symbol-name of @var{name}.
+
address@hidden :program-name-variable @var{variable}
+The variable specifying the backend executable.  The default defines a
+variable @address@hidden, bound to the value of
address@hidden
+
address@hidden :program-arguments @var{list}
+A list of program arguments, to be processed by
address@hidden  The default is
address@hidden(@var{extra-program-arguments-variable} bongo-extra-arguments
+bongo-file-name)}.
+
address@hidden :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
address@hidden, if its name is mentioned in
address@hidden  A null value means no variable will be
+defined.  The default defines a variable
address@hidden@var{name}-extra-arguments}.
+
address@hidden :extra-program-arguments @var{list}
+The initial value for the @var{extra-program-arguments-variable}
+variable.  The default is @code{nil}.
+
address@hidden :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
address@hidden(name . properties)} where @code{properties} is an alist.
+
+The default defines a function @address@hidden
+which calls @code{bongo-start-simple-player}.
+
address@hidden :pause-signal @var{sigcode}
+The signal used with @code{signal-process} to pause the player
+process.  The default is @code{SIGSTOP}.
address@hidden table
address@hidden defmac
 
 @node GNU GPL
 @appendix GNU General Public License