diff options
Diffstat (limited to 'source-builder/sb/asciidoc/doc/music-filter.txt')
-rw-r--r-- | source-builder/sb/asciidoc/doc/music-filter.txt | 148 |
1 files changed, 0 insertions, 148 deletions
diff --git a/source-builder/sb/asciidoc/doc/music-filter.txt b/source-builder/sb/asciidoc/doc/music-filter.txt deleted file mode 100644 index 1daa70b..0000000 --- a/source-builder/sb/asciidoc/doc/music-filter.txt +++ /dev/null @@ -1,148 +0,0 @@ -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). |