diff options
Diffstat (limited to 'doc/asciidoc/examples/website/music-filter.txt')
| -rw-r--r-- | doc/asciidoc/examples/website/music-filter.txt | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/doc/asciidoc/examples/website/music-filter.txt b/doc/asciidoc/examples/website/music-filter.txt new file mode 100644 index 0000000..1daa70b --- /dev/null +++ b/doc/asciidoc/examples/website/music-filter.txt @@ -0,0 +1,148 @@ +Music Filter +============ + +The AsciiDoc distribution includes a Music Block filter that +translates music in http://lilypond.org/[LilyPond] or +http://abcnotation.org.uk/[ABC] notation to standard classical +notation in the form of a trimmed PNG image which is automatically +inserted into the AsciiDoc output document (see the examples below). + +Actually the filter (`./filters/music/music2png.py`) can be used outside +AsciiDoc to convert LilyPond or ABC music files to PNG images. +Execute the following command to see how to use it: + + $ ./filters/music/music2png.py --help + +.Music Block containing ABC notation +===================================================================== + +This Music Block: + +[listing] +..................................................................... +["music","music1.png",scaledwidth="100%"] +--------------------------------------------------------------------- +T:The Butterfly +R:slip jig +C:Tommy Potts +H:Fiddle player Tommy Potts made this tune from two older slip jigs, +H:one of which is called "Skin the Peelers" in Roche's collection. +H:This version by Peter Cooper. +D:Bothy Band: 1975. +M:9/8 +K:Em +vB2(E G2)(E F3)|B2(E G2)(E F)ED|vB2(E G2)(E F3)|(B2d) d2(uB A)FD:| +|:(vB2c) (e2f) g3|(uB2d) (g2e) (dBA)|(B2c) (e2f) g2(ua|b2a) (g2e) (dBA):| +|:~B3 (B2A) G2A|~B3 BA(uB d)BA|~B3 (B2A) G2(A|B2d) (g2e) (dBA):| +--------------------------------------------------------------------- +..................................................................... + +Renders: + +["music","music1.png",scaledwidth="100%"] +--------------------------------------------------------------------- +T:The Butterfly +R:slip jig +C:Tommy Potts +H:Fiddle player Tommy Potts made this tune from two older slip jigs, +H:one of which is called "Skin the Peelers" in Roche's collection. +H:This version by Peter Cooper. +D:Bothy Band: 1975. +M:9/8 +K:Em +vB2(E G2)(E F3)|B2(E G2)(E F)ED|vB2(E G2)(E F3)|(B2d) d2(uB A)FD:| +|:(vB2c) (e2f) g3|(uB2d) (g2e) (dBA)|(B2c) (e2f) g2(ua|b2a) (g2e) (dBA):| +|:~B3 (B2A) G2A|~B3 BA(uB d)BA|~B3 (B2A) G2(A|B2d) (g2e) (dBA):| +--------------------------------------------------------------------- +===================================================================== + + +.Music Block containing LilyPond notation +===================================================================== +This example contains LilyPond musical markup. + +[listing] +..................................................................... +[music] +--------------------------------------------------------------------- +\version "2.14.2" +\paper { + ragged-right = ##t +} +{ + \time 3/4 + \clef bass + c2 e4 g2. f4 e d c2 r4 +} +--------------------------------------------------------------------- +..................................................................... + +Renders: + +[music] +--------------------------------------------------------------------- +\version "2.14.2" +\paper { + ragged-right = ##t +} +{ + \time 3/4 + \clef bass + c2 e4 g2. f4 e d c2 r4 +} +--------------------------------------------------------------------- +===================================================================== + +NOTE: If you get an error processing the above example it may be that +it is not compatible with your version of LilyPond. Use the LilyPond +`convert-ly(1)` utility to update the source to the version that you +are using. + + +Using the Filter +---------------- +- The Music filter is invoked by setting the Listing block or + Paragraph style (the first positional block attribute) to 'music'. +- The second positional attribute (named 'target' is optional, it sets + the name of the generated PNG image file. If this is not supplied a + file name like `{docname}__{target-number}.png` is synthesised + (where `{docname}` is the document file name and `{target-number}` + is an integer number. +- The third positional attribute ('format') specifies the music input + format: either 'abc' for ABC or 'ly' for LilyPond. If the format is + omitted ABC notation is assumed unless the text starts with a + backslash character, in which case the format is set to 'ly'. + +Because the LaTeX images are rendered using the image block templates +you can also use the optional named image block attributes (see +link:userguide.html#X55[Image macro attributes] in the AsciiDoc User +Guide). + + +Limitations +----------- +- The `asciidoc(1)` input and output files cannot both be `-` (stdin + and stdout), either the input or output files (or both) must be a + named file. + + +Installation +------------ +In addition to AsciiDoc you will need to have installed: + +- http://lilypond.org/web/[LilyPond] (most Linux distributions include + this package). +- http://www.imagemagick.org[ImageMagick] (most Linux distributions + include this package). + +Test the music filter it by converting the test file to HTML with AsciiDoc: + + $ asciidoc -v ./filters/music/music-filter-test.txt + $ firefox ./filters/music/music-filter-test.html & + +The filter was developed and tested on Xubuntu Linux using LilyPond +2.10.5 and ImageMagick 6.2.4. + +NOTE: The filter does not work with LilyPond 2.2.6 because it did not +generate the requested output file name correctly (2.6.3 does not have +a problem). |