Extension:abcExport

abcExport Release status: beta
Implementation	Page action, Special page
Description	provides a special page for exporting content from pages containing abc music notation in abc or pdf formats
Author(s)	Lawrie Brown
Latest Version	1.1
License	CC By NC SA
MediaWiki	tested on 1.29+
Download	http://bushtraditions.wiki/tunes/extensions/abcExport.zip

The abcExport extension provides a special page for exporting content from pages containing abc music notation in abc or pdf formats.

This extension is most likely used along with the ABCjs extension that supports input, tagging & display of abc music notation.

Installation
Configuration
Usage
- Special page
- Toolbox links
Technical Details
See also
Acknowledgements

Installation

Installation of abcExport requires both installing the extension into your wiki, and also installing the required helper programs if you want to support pdf score export.

Download and unzip so the files are saved in a directory called abcExport in your extensions/ folder.
Install the abcm2ps and gs utility programs if pdf export wanted (see below).
Add the following code at the bottom of your LocalSettings.php:
```
wfLoadExtension('abcExport');
```
Configure as required.
Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

For conversion of abc music notation to pdf, you need:

abcm2ps - a command line program which converts ABC to music sheet in PostScript. You may be able to install it from a package on your O/S, otherwise build from source.
gs (Ghostscript) - an interpreter for the PostScript language and for PDF, that is usually available on most systems, or can be installed from package if not.

Configuration

You can then redefine any of the following globals after the require_once statement in your LocalSettings.php:

$wgabcExport_abcm2ps

full path to abcm2ps command (or null if missing). If set to null, pdf score export is not available. Default "/usr/bin/abcm2ps"
It can also include command-line arguments to abcm2ps, such as reference to a "format file" with additional abc rendering options, e.g.

$wgabcExport_abcm2ps = "/usr/bin/abcm2ps -F /somepath/to/share/abcm2ps/morefields.fmt" ;

$wgabcExport_gs

full path to gs command. Default "/usr/bin/gs"

$wgabcExport_abcTag

start tag for abc content (same as used in the ABCjs extension). Default <pre id=abc>

$wgabcExport_abcTagEnd

end tag for abc content (same as used in the ABCjs extension). Default </pre>

$wgabcExport_mungeNames

whether to munge tune names by moving any leading The/An/A to the end in brackets, per site policy. Default true

$wgabcExport_addFileURL

whether to add F: file URL tag to the source page for the tune to the exported abc. Default true

See abcExport/extension.json in your extensions/ folder for the default values of these variables.

Usage

Special page

The special page for this extensions is listed under Special:SpecialPages as Export abc tunes in the Page tools section. You can also access it directly using the Export multiple tunes toolbox link (see below). The page looks like this:

To use the export feature, you first need to list the pages with tune content. You can edit or add to this list of one or more tune/page titles that you want to export abc tunes from, one title per line. You can delete any unwanted tunes, or to change their order in the list, but remember to keep one tune/page title per line, which must exactly match the tune/page title. Or you can copy and paste a list of tunes titles from a text file on your computer into this list. Or you can tag a series of tunes for later export, which will be added to this list in order (provided you have Mediawiki 1.27+ with Session Manager support).

Note that any leading The/An/A will be moved to end per site policy for tune page names, if needed. And that spaces are replaced by '_' if needed. Both of these are already done for tagged tune names.

Lines starting with % are abc comments or directives (eg %%newpage) that will be copied directly into the abc file.

Once you are satisfied with your list, you should specify the desired export filename, select the desired export format (abc music notation file, pdf rendered score, or this list as a text file), the "Export Tunes" action, and then select the "Do It!" button to download the content in your chosen format.

You can navigate away to search for and tag other tunes to add to the list ((provided you have Mediawiki 1.27+). Tagged tunes will appear in this list, in the order tagged, unless the list has been cleared, or reset by exporting a single tune. If you make any changes to the list on this page, you must select either the 'Export Tunes' or 'Remember List Changes' action to save your changes before leaving this page. Please note that your tune list is only saved for the duration of this web session. You need to use it to export tunes, export it as text, or copy and paste it into a text file on your computer, before closing your browser.

Toolbox links

This extension also adds a number of extra links into the Tools Navigation Toolbox (usually on the LHS), as shown:

These links provide the following functionality:

Export this tune abc
Immediately export any abc music notation content on the current page to filename Page_title.abc and stay on this page.
Export this pdf score
Immediately render any abc music notation content on the current page as a PDF score and export to filename Page_title.pdf and stay on this page.
Tag for later export
Add the current page title to the list of tune/page names used by the abcExport special page, and redirect back to this page.
Export multiple tunes
Navigate to the abcExport special page, which will have any tagged tunes/pages listed, and which you can then edit and use as described described above.

Technical Details

This extension adds a special page Special:AbcExport that allows for multiple page titles to be entered, or accessed if previously tagged. This page displays the list of tunes tagged for export in the current browser session, which can edited or extended. It provides options to select the export format (abc, pdf, or txt list of tunes), actions available, and the "Do It!" (Submit) button to perform them. It uses the Session Manager included in Mediawiki 1.27+ to remember tagged tune names, and the list of tagged tunes, for the current browser session. It also adds several new Navigation toolbox links to export tunes from the current page (as abc or pdf), tag page, or access this special page, by adding hooks to SidebarBeforeOutput.