LenMus eMusicBooks are written in HTML. Scores an interactive exercises are embedded by using the <object> tag. All the html pages that form an eMusicBook are packaged using a reduced version of Microsoft's HTML Help Workshop project files (.hhp, .hhk, .hhc, .htm).
A book consists of three main files: a header file (.hhp), a table of contents file (.hhc) and an index file (.hhk), and as many page files (.htm) as you would like. In addition you have to include any image files you need. All these files are packaged into a single zip archive; and the .zip file must be renamed to .htb (htb stands for "html book").
The header file (also known as project file) describes a book. Basically, it contains the book title and references to the table of content file and the index file, as well as some parameters. There must exists one header file per book.
Header file must contain these lines (and may contain additional lines which will be ignored):
Contents file=<filename.hhc> Title=<title of this book> Default topic=<default_page_to_be_displayed.htm>
All filenames (including the Default topic) are relative to the location of .hhp file.
In addition, an .hhp file may contain the line
Charset=<rfc_charset>
which specifies what charset (e.g. "ISO-8859-1") was used in contents and index files. Please note that this line is incompatible with MS HTML Help Workshop and it would either silently remove it or complain with some error.
Optionally, if an index file has been compiled, the header file must contain a line like:
Index file=<filename.hhk>
to specify the associated index file.
The contents file describes the TOC for one book. It has HTML syntax and contains exactly one list (<ul>....</ul> statement) but items in this main list may contain nested sub lists, to describe, for example, the content of the chapters and sections. Here is an example:
<! DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <html> <head> <!-- Example of Table of content file --> </head> <body> <ul> <li> <object type="text/sitemap"> <param name="Name" value="Chapter 1. Introduction"> <param name="Local" value="Book1Chaper1.htm"> </object> <li> <object type="text/sitemap"> <param name="Name" value="Chapter 2. Intervals”> <param name="ID" value=34> <param name="Local" value=" Book1Chaper2.htm"> </object> <ul> <li> <object type="text/sitemap"> <param name="Name" value="2.1 Simple intervals"> <param name="Local" value="Book1Section1.htm"> </object> </ul> </ul> </body> </html>
The value of param Name is the name of the chapter/topic as you would like it to be displayed in the table of contents.
The value of param Local is the filename of the HTML page associated to that content. Filename must include the relative path to base folder containing the .hhp file.
The param ID is optional, and it is used only when a page will be displayed, programmatically, from the program, for example, for context sensitive help display. Its value is a unique number, to be use by the program to refer to that page.
The index file contains a list of terms/words with a reference to the relevant book/page where each term appears.
The index file has the same format as a content file except that ID params are ignored and sub lists are not allowed. Here is an example:
<! DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <html> <head> <!-- Index file example --> </head> <body> <ul> <li> <object type="text/sitemap"> <param name="Name" value="Interval, definition"> <param name="Local" value="Book3Page7.htm"> </object> <li> <object type="text/sitemap"> <param name="Name" value="Interval, minor an major"> <param name="Local" value="Book3Page8.htm"> </object> </ul> </body> </html>
Page files are the documents to display, written in standard HTML with the restrictions and additions described in the rest of this documentation.
Warning about testing
When displaying the documentation, the LenMus program creates cached binary versions of index and contents files and store them in the lenmus/temp/ directory. These binary forms are much faster to read. But note that these files are not deleted when program exits. If these files are present, the source header, content and index files will no be read. So for testing, if you modify one of these files, be sure that you delete the corresponding cache file; otherwise you will not see any modification!!
The HTML browser implemented in LenMus program is based on wxWidgets facilities. This is not a full implementation of the HTML standard. But it supports the most common tags so that it is possible to create and display complex documents with good formatting. For example it works fine with pages created in Netscape Composer.
Following tables list all supported tags, together with supported attributes. A tag has general form
<tagname attrib_1 attrib_2 ... attrib_n>
where attrib_i has the form:
attribute_name="value"
To follow the XHTML standard all tags and attributes have to be in lower case letters.
a name=[string] href=[url] target=[target window spec] address area shape=poly shape=circle shape=rect coords=[coords] href=[url] b big blockquote body text=[color] link=[color] bgcolor=[color] br align=[alignment] center cite code dd div align=[alignment] dl dt em font color=[color] size=[fontsize] face=[comma-separated list of facenames] hr align=[alignment] size=[pixels] width=[percent|pixels] noshade h1 h2 h3 h4 h5 h6 i img src=[url] width=[pixels] height=[pixels] align=texttop align=center align=abscenter align=bottom usemap=[url] kbd li map name=[string] meta http-equiv="content-type" content=[string] ol p align=[alignment] pre samp small strike strong table align=[alignment] width=[percent|pixels] border=[pixels] valign=[v_alignment] bgcolor=[color] cellspacing=[pixels] cellpadding=[pixels] td align=[alignment] valign=[v_alignment] bgcolor=[color] width=[percent|pixels] colspan=[pixels] rowspan=[pixels] th align=[alignment] valign=[v_alignment] bgcolor=[color] width=[percent|pixels] colspan=[pixels] rowspan=[pixels] title tr align=[alignment] valign=[v_alignment] bgcolor=[color] tt u ul
These are the valid values for the attributes before described:
[alignment] center left right justify [v_alignment] top bottom center [color] HTML 4.0-compliant colour specification [fontsize] -2 -1 +0 +1 +2 +3 +4 1 2 3 4 5 6 7 [pixels] integer value that represents dimension in pixels [percent] i% where i is integer [url] an URL [string] text string [coords] c(1),c(2),c(3),...,c(n) where c(i) is integer
In addition to the previous listed tags, the <object> tag must be used to include LenMus program content, such as scores, interactive exercises and musical symbols.
By using the <object> tag we ensure compliance with the HTML standard so that LenMus eMusicBooks and documentation can be displayed in any web browser, although the LenMus specific features will not be displayed unless a plug-in is included in the browser. But, in any case, you will be able to display the book and no error will be shown.
Params for lmScoreCtrol - html object type="Application/LenMusTheoSideReading" optional params to include controls: (not yet implemented marked as []) -------------------------------------- control* one param for each control to include. value="play" include 'play' link. Default: include it. [value="solfa"] include 'solfa' link. Default: do not include it. control_settings Value="[key for storing the settings]" This param forces to include the 'settings' link. The key will be used both as the key for saving the user settings and as a tag to select the Setting Dialog options to allow. control_go_back URL, i.e.: "v2_L2_SideReading_203.htm" [label_play] "play label|stop playing label". i.e.: "Play|Stop" Stop label is optional. Default labels: "Play|Stop playing" [label_solfa] "side read label|stop side reading label". i.e.: "Play|Stop" Stop label is optional. Default labels: "Side read|Stop reading" params to set up the score composer: ------------------------------------ fragment* one param for each fragment to use clef* one param for each allowed clef. It includes the pitch scope. time a list of allowed time signatures, i.e.: "68,98,128" key keyword "all" or a list of allowed key signatures, i.e.: "Do,Fas" maxInterval a number indicating the maximum allowed interval for two consecutive notes Default: 4 Example: ------------------------------------ <object type="Application/LenMusTheoSideReading" width="100%" height="300" border="0"> <param name="control" value="play"> <param name="label_play" value="Play|Stop"> <param name="control" value="solfa"> <param name="mode" value="PersonalSettings"> <param name="mode" value="NotesReading"> <param name='fragment' value='24,34,44;(s c)(n * c),(n * c g+)(n * c +l g-),(n * c g+)(n * s)(n * s g-),(n * c g+)(n * c g-),(n * n)'> <param name='fragment' value='24,34,44;(n * c g+)(n * c +l g-),(n * c g+)(n * s)(n * s g-),(n * n.)(n * c),(n * s g+)(n * s)(n * s)(n * s g-),(n * s g+)(n * s)(n * s)(n * s g-),(n * c g+)(n * c +l g-),(n * n)'> <param name='fragment' value='24,34,44;(n * c g+)(n * c +l g-),(n * c g+)(n * s)(n * s g-),(n * c g+)(n * c)(n * c)(n * c g-),(n * c)(n * n.)'> <param name='fragment' value='24,34,44;(n * c g+)(n * c)(n * c)(n * c +l g-),(n * c g+)(n * s)(n * s g-),(n * s g+)(n * s)(n * s)(n * s g-),(n * n),(n * n)'> <param name='fragment' value='34,44;(n * n)(n * c)(n * n)(n * c)(n * c g+)(n * c g-)(n * c g+)(n * c +l g-)(n * c g+)(n * s)(n * s g-)(n * c g+)(n * s)(n * s g-)(n * c g+)(n * c +l g-)(n * n)'> <param name='fragment' value='24,34,44;(s c)(n * c),(n * s g+)(n * s)(n * s)(n * s g-),(n * c)(n * n)(n * s g+)(n * s g-),(n * b)'> <param name="clef" value="Sol;a3;a5"> <param name="clef" value="Fa4;a2;e4"> <param name="time" value="24,34,44"> <param name="key" value="all"> <param name="maxInterval" value="4"> </object>
Fragments will be divided into 'segments'. Each segment division line is a point in wich a barline can be inserted: =====|=============|============|===============|======= In some cases the pattern represented by the fragment requires a certain barline alignment. Let's define: tam - Time to align to barline ('am' stands for 'align to measure') <------------- tam -------------> =====|=============|============||===============|======= If a fragment does not require any special alignment for a barline then tam=0 A fragment can start in any place, not necesarily aligned to beat. Therefore there will be a required time to align to beat: tab - Time to align to beat ('ab' stands for 'align to beat') <--tab--><------------- tam -------------> | =====|=============|============||===============|======= If the fragment starts aligned to beat then tab=0 In theory, a fragment will never start with rests, as starting with a rest is equivalent to not being beat aligned. Important: in practice, the way of indicate that the fragment is not beat aligned is by starting the segment with rests. These rests will be removed by the program and its duration will be assigned to time tab.
Fragments are encoded in LDP language
Are composed of notes and rests. Notes will not have pitch; instead an asterisk (*) must be placed.
Fragments must be in LDP normal form: right case, no extra spaces.
The point at which a barline can be inserted must be marked by a comma (,)
The point at which a barline must be inserted must be marked by a vertical bar (|)
Examples:
<param name='fragment' value='24;(n * c g+)(n * c +l g-),(n * c g+)(n * s)(n * s g-)'> <param name='fragment' value='24,34,44;(s c)(n * c),(n * c g+)(n * c +l g-),(n * c g+)(n * s)(n * s g-),(n * c g+)(n * c g-),(n * n)'> <param name='fragment' value='24,34,44;(n * c g+)(n * c +l g-),(n * c g+)(n * s)(n * s g-),(n * n.)(n * c),(n * s g+)(n * s)(n * s)(n * s g-),(n * s g+)(n * s)(n * s)(n * s g-),(n * c g+)(n * c +l g-),(n * n)'> <param name='fragment' value='24,34,44;(n * c g+)(n * c +l g-),(n * c g+)(n * s)(n * s g-),(n * c g+)(n * c)(n * c)(n * c g-),(n * c)(n * n.)'> <param name='fragment' value='24,34,44;(n * c g+)(n * c)(n * c)(n * c +l g-),(n * c g+)(n * s)(n * s g-),(n * s g+)(n * s)(n * s)(n * s g-),(n * n),(n * n)'> <param name='fragment' value='34,44;(n * n)(n * c)(n * n)(n * c)(n * c g+)(n * c g-)(n * c g+)(n * c +l g-)(n * c g+)(n * s)(n * s g-)(n * c g+)(n * s)(n * s g-)(n * c g+)(n * c +l g-)(n * n)'> <param name='fragment' value='24,34,44;(s c)(n * c),(n * s g+)(n * s)(n * s)(n * s g-),(n * c)(n * n)(n * s g+)(n * s g-),(n * b)'>