--- abcmplugin ---


Overview
========

'abcmplugin' is a simple plugin which renders ABC tunes in WEB browsers
thanks to 'abcm2ps'.

It is called either implicitly when loading .abc files (either local
or remote when the HTTP server returns the MIME type'text/vnd.abc')
or explicitly using <object> or <embed> HTML tags.


Generation - installation
=========================

You first need a working binary of 'abcm2ps' version >= 7.6.8.

Actually, there is no 'configure' script for the plugin, but the generation
of 'abcmplugin.so' should work in most Unix-like systems with 'gcc',
the GNU C compiler, or 'clang'.
If you use some other C compiler, update the file 'Makefile'.

Doing
	make
in the distribution directory generates the shared library 'abcmplugin.so'.

This library must be put in some well-known directory where your
browser searches the plugins (as '/usr/lib/mozilla/plugins/').


Usage
=====

When you load a local ABC file (extension '.abc'), the plugin replaces
the original file by a XHTML file containing SVG images. These images are
generated by 'abcm2ps' with the output option '-X' (one SVG image per page).

The plugin may also be explicitly called in HTML or XHTML documents by
<object> and <embed> tags which may contain the properties
	- 'abcm2ps' the value of which is given as the command line options
	  to the process abcm2ps for ABC rendering.
	- 'abc' the value of which is a ABC sequence to be rendered.
After generation, the <object> or <embed> is replaced by a list of SVG
images possibly followed by a <pre> sequence containing the found errors.
The images are generated by 'abcm2ps' with the output option '-v' (raw SVG
images).

See 'plugin.html' for an example.


Advanced usage
==============

When the plugin is called, after abcm2ps generation, the javascript function
'abcmimg' is called with the arguments:
	- elt	the <object> / <embed> element.
	- img	the raw SVG images optionnaly followed by the errors in <pre>,
		or the .xhtml output when '-X' is given in the abcm2ps
		properties.

When this function is absent from the HTML/XHTML document, the following
default one is inserted:

	function abcmimg(elt, img) {
		elt.outerHTML = img;
	}

which simply replaces the element by the image(s).

See 'edit.xhtml' for an example of how this function may be extended.


Limitations
===========

The actual abcmplugin compiles and works only in Unix-like systems with
WEB browsers offering the scriptable NPAPI (as Gecko based browsers -
Firefox, Iceweasel - , Opera, midori, dwb ...).

Rendering uses temporary files in /tmp/.

When the ABC file is remote and when the serveur does not return the type
'text/vnd.abc' for ABC files, the music rendering does not work.


Contacts
========

The primary abcmplugin site is:

	http://moinejf.free.fr/