LenMus eMusicBooks format

Table of Contents

Introduction
1. File format
2. Header file
3. Contents files
3. Index file
4. Page files
5. HTML tags supported
6. The OBJECT tag
6.1. SideReadingCtrolParams
6.2. Fragment syntax
6.3. The Time element
6.4. The Barline element
8. Notes, rests and chords
8.1. Pitch
8.2. Duration

File format

TOC

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").

Header file (.hhp)

TOC

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.

Contents files (.hhc)

TOC

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.

Index file (.hhk)

TOC

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 (.htm)

TOC

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!!

HTML tags supported

TOC

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.

List of supported tags

TOC
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
 

Table of values

TOC

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
 

The OBJECT tag

TOC

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.

SideReadingCtrolParams

TOC
    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>

Fragment syntax

TOC
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.

Rules

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)'>