Handbook: addition of the Snippet chapter

docs/_pages/specific/README.md

@@ -7,6 +7,3 @@ has_children: true
 # Specific Features
 
 Meant for the end-user, this chapter gathers features that deserve a specific description.
-
-{: .highlight }
-For 5.3 release, all these specific features are also **NEW** features.

docs/_pages/specific/drums.md

@@ -8,12 +8,12 @@ has_children: false
 ## Drums
 {: .no_toc }
 {: .d-inline-block }
-new in 5.3
-{: .label .label-yellow }
+updated for 5.4
+{: .label .label-green}
 
 We owe many thanks to Brian Boe for his decisive contribution to this long-awaited functionality.
 
-First requests for drums notation go back to 2017,
+The first requests for drum notation go back to 2017,
 see Audiveris [issue #33](https://github.com/Audiveris/audiveris/issues/33). 
 This delay certainly originated in my personal ignorance (Hervé speaking) about this kind of notation.
 
@@ -26,39 +26,60 @@ Table of contents
 ### Example
 
 This [Wikipedia article](https://en.wikipedia.org/wiki/Percussion_notation) provides a good
-introduction to drums notation.  
+introduction to drum notation.
 
-Since 5.3 release, Audiveris supports drums unpitched notation on both 5-line and 1-line staves,
-as shown in the following excerpt:
+Since the 5.3 release, Audiveris supports unpitched precussion notation on both 5-line and 1-line staves,
+as shown in the excerpt below.
+
+{: .highlight }
+Note this handbook contains a [User editing session](../ui_examples/eyes/README.md) dedicated to this precise score example.
 
 ![](../assets/images/drums_stave_sizes.png)
 
 1. Each staff starts with a percussion clef,
 2. Each individual instrument is defined by a given head motif at a given line position  
    (drum set mapping).
-3. Though not specific to drums notation, we can frequently observe
+3. Though not specific to drum notation, we can frequently observe
 [multi-measure rests](./multi_rest.md) and [measure-repeat signs](./bar_repeat.md).
 
-### Processing switches
+### Mandatory processing switches
 
 To be able to transcribe the example above, we have to set two specific processing book parameters,
-available in dialog ``Book | Set Book Parameters``, one for 1-line
-and one for 5-line percussion stave sizes:
+available in the dialog ``Book | Set Book Parameters``, in the section named "Staves",
+one for 1-line and one for 5-line percussion stave sizes:
 
 ![](../assets/images/drums_params_2sizes.png)
 
-In batch mode, we can also set these switches at command line interface level:
+In batch mode, we can also set these switches at the command line interface level:
 > -option org.audiveris.omr.sheet.ProcessingSwitches.oneLineStaves=true
 
 > -option org.audiveris.omr.sheet.ProcessingSwitches.drumNotation=true
 
+### Additional switches
+
+Beside the two mandatory switches, it is worth paying attention to two other lines:
+- One is the "**Barline height**", located just above, in the "Scaling specifications".
+In fact, this line is usually hidden.
+It gets visible only when we set the "1-line percussion staves" switch to on.  
+On a multi-line staff, a barline is expected to go from the top line to the bottom line.
+But on a 1-line staff, what should be the height of barlines?
+In the example at hand, as in many other examples, the barlines exhibit the same height,
+whether they belong to a 5-line staff or to a 1-line staff, that is four interlines
+which is the default value.
+
+- Another one is the processing switch named "**5-line standard staves**".
+Since there are no such staves in the example, we can explicitly tell the engine that there are none.  
+It has no concrete impact on the example at hand, because there are other multi-line staves
+available for the OMR engine to measure the score interline value.  
+This switch will get more important when we address the case of [Snippets](./snippets.md).
+
 ### Drum set mapping
 
-There seems to be no universal specification for drum set mapping, only some recommandations.  
-This means that, depending on a score author, the mapping can be different.
+There seems to be no universal specification for drum set mapping, only some recommendations.  
+This means that, depending on score author, the mapping can be different.
 
 Audiveris provides a default mapping via the ``drum-set.xml`` file in its ``res`` resource folder.  
-Content of this XML file is listed in [appendix](#appendix).
+The content of this XML file is listed in the [appendix](#appendix).
 
 Within the ``drum-set`` XML root element, there is one ``staff`` XML element per staff size 
 (one for 1-line staves, one for 5-line staves).
@@ -68,28 +89,28 @@ The mapping definition is a list of entries within the containing ``staff`` XML
 - Each ``entry`` XML element contains the following XML attributes:
     - "``pitch-position``": line/space number (0 being the mid-line, values increasing top down)
     - "``motif``": general head shape (oval, small, cross, diamond, triangle, circle)
-    - "``sound``": intrument name (Acoustic_Bass_Drum, etc. see appendix)
+    - "``sound``": intrument name (Acoustic_Bass_Drum, etc. see the appendix)
     - "``sign``": this attribute is optional, it indicates a playing technique
     (PLAYING_OPEN, PLAYING_HALF_OPEN, PLAYING_CLOSED)
 
 This protected resource is just the *default* mapping:
 - As an end-user, we can always incrementally override some or all of the default mapping entries,
 by writing our own entries in a similar but certainly smaller ``drum-set.xml`` file to be located
-in user ``config`` folder.
+in theh user ``config`` folder.
 - To "nullify" an existing default entry, we simply specify a "``null``" value
 for its "``sound``" attribute.
 
 ### Transcription
 
-Among the examples used when working on drums with Brian, we can recommand the
+Among the examples used when working on drums with Brian, we can recommend the
 [Redeye Percussion](https://www.redeyepercussion.com/) site.  
 Its "Sheet Music" top link gives access to hundreds of percussion scores.
 
 Here below is the example of
 [Ophelia](https://www.redeyepercussion.com/music/Ophelia_TheBand_redeyepercussion.com.pdf),
 a simple one-page score.
 
-Beginning of the PDF file, downloaded from Redeye Percussion site, is as follows:
+The beginning of the PDF file, downloaded from Redeye Percussion site, is as follows:
 
 ![](../assets/images/drums_ophelia.png)
 
@@ -129,11 +150,11 @@ appear away from heads.
 
 ## Appendix
 
-Here below is the content of ``drum-set.xml`` file provided in Audiveris ``res``
+Here below is the content of the ``drum-set.xml`` file provided in the Audiveris ``res``
 application folder.
 
 Remember the end user can still override some default definitions
-via a similar ``drum-set.xml`` file to be located in user ``config`` folder.
+via a similar ``drum-set.xml`` file to be located in the user ``config`` folder.
 
 ```xml
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
@@ -144,11 +165,11 @@ via a similar ``drum-set.xml`` file to be located in user ``config`` folder.
 <!-- =========================================================================================== -->
 
 <!--
-    This file, located in Audiveris 'res' folder, defines drum default mapping.
-    The end-user can override part or whole of this mapping by writing a specific drum-set.xml file
-    located in Audiveris user 'config' folder.
+    This file, located in the Audiveris 'res' folder, defines the default drum mapping.
+    The end-user can override part or all of this mapping by writing a specific drum-set.xml file
+    located in the Audiveris user 'config' folder.
 
-    Such file defines Audiveris entries for general midi percussion keys.
+    Such a file defines Audiveris entries for general midi percussion keys.
     Definitions are grouped by staff line count with one attribute:
     
     - line-count        (Mandatory)
@@ -174,7 +195,7 @@ via a similar ``drum-set.xml`` file to be located in user ``config`` folder.
     - sound:            (Mandatory)
                         name of drum sound
                         The name must contain no space, no dash, just underscores.
-                        A null sound value removes the entry at (pitch-position,motif,sign) tuple
+                        A null sound value removes the entry at the (pitch-position,motif,sign) tuple
                         For a comprehensive list of sound names, please refer to
                         https://computermusicresource.com/GM.Percussion.KeyMap.html 
                   
@@ -183,7 +204,18 @@ via a similar ``drum-set.xml`` file to be located in user ``config`` folder.
 <drum-set>
 
   <staff line-count="1">
-    <entry pitch-position="0"  motif="oval"    sound="null"/> <!-- Just a place-holder -->
+
+    <!-- -1 -->
+    <entry pitch-position="-1" motif="oval"  sound="Hi_Bongo"/>
+    <entry pitch-position="-1" motif="cross" sound="Maracas"/> <!-- Surely wrong... -->
+
+    <!-- 0 -->
+    <entry pitch-position="0"  motif="oval"  sound="Hand_Clap"/>
+
+    <!-- 1 -->
+    <entry pitch-position="1"  motif="oval"  sound="Low_Bongo"/>
+    <entry pitch-position="1"  motif="cross" sound="Cowbell"/>
+
   </staff>
 
   <staff line-count="5">
@@ -239,7 +271,7 @@ via a similar ``drum-set.xml`` file to be located in user ``config`` folder.
     <entry pitch-position="1" motif="oval"      sound="High_Floor_Tom"/>
 
     <!-- 2 -->
-    <entry pitch-position="1" motif="oval"      sound="Low_Floor_Tom"/>
+    <entry pitch-position="2" motif="oval"      sound="Low_Floor_Tom"/>
     <entry pitch-position="2" motif="cross"     sound="Low_Conga"/>
     <entry pitch-position="2" motif="circle"    sound="Low_Conga"/>
 
@@ -258,8 +290,9 @@ via a similar ``drum-set.xml`` file to be located in user ``config`` folder.
 
 <!--
     Here below is the list of not yet assigned sounds
-    To actually assign one sound, replace the "null" values by actual pitch-position and motif
-    -->
+    To actually assign one sound, uncomment the line and replace the "null" values
+    by actual pitch-position and motif.
+    
     <entry pitch-position="null" motif="null" sound="Hand_Clap"/>
     <entry pitch-position="null" motif="null" sound="Vibraslap"/>
     <entry pitch-position="null" motif="null" sound="Electric_Snare"/>
@@ -283,9 +316,10 @@ via a similar ``drum-set.xml`` file to be located in user ``config`` folder.
     <entry pitch-position="null" motif="null" sound="Open_Cuica"/>
     <entry pitch-position="null" motif="null" sound="Mute_Triangle"/>
     <entry pitch-position="null" motif="null" sound="Open_Triangle"/>
-
+    -->
+
   </staff>
-
+  
 </drum-set>
 ```
 

docs/_pages/specific/snippets.md

@@ -0,0 +1,117 @@
+---
+layout: default
+title: Snippets
+parent: Specific Features
+nav_order: 0
+has_children: false
+---
+## Snippets
+{: .no_toc }
+{: .d-inline-block }
+new in 5.4
+{: .label .label-yellow }
+
+Tiny pieces of music can be found on the Internet, generally for illustration purpose.
+For example, this [Wikipedia page](https://en.wikipedia.org/wiki/Fandango) is about the Fandango dance.
+It provides some explanation text, a picture of fandango dancers and a snippet of music score to
+describe the specific fandango rhythm:
+
+![](../assets/images/fandango_wikipedia.png)
+
+For the Audiveris OMR engine, the processing of such a tiny score brings a few challenges.
+
+Table of contents
+{: .no_toc .text-delta }
+1. TOC
+{:toc}
+---
+
+### Challenges
+
+Let's have a closer look at this image (By Hyacinth, CC BY-SA 3.0, https://commons.wikimedia.org/w/index.php?curid=27409005):
+
+![](../assets/images/Fandango_dance_pattern.png)
+
+#### Interline
+
+If we naively launch Audiveris on this input image, we almost immediately get this alert message:
+
+![](../assets/images/fandango_scale_alert.png)
+
+The engine complains about a too low interline value of 9 pixels.
+This message is issued by the ``SCALE`` step, whose main task is to retrieve the sheet "interline value",
+which is the main vertical distance, in pixels, between two staff lines.
+
+This is a key value, because it determines the general scale of the image, and will drive the following steps
+such as the heads recognition.
+
+It is retrieved by the ``SCALE`` step, via the analysis of the so-called "combo histogram", 
+populated with the vertical runs lengths of the image.
+The engine measures any vertical black run followed by a vertical white run.
+The total length is recorded in the combo histogram, which then exhibits a very visible peak at the
+interline value.
+For further details, please refer to the [Sheet Scale chapter](../main/sheet_scale.md).
+
+But in the case of our snippet, the image contains just one staff line.
+Therefore, there is no physical "interline" the engine could retrieve.
+
+For the sake of completion, here below are the black histogram and the combo histogram:
+
+| Legend | Histogram|
+| :---   | :---:|
+|The black histogram gives correct values for the typical staff line height (4 pixels) and the typical beam height (16 pixels) | ![](../assets/images/fandango_black_histogram.png) |
+|The combo histogram should give the typical interline value, but provides only erratic values | ![](../assets/images/fandango_combo_histogram.png)|
+
+#### Barline height
+
+Another consequence of the lack of multi-line staves in the input image concerns the typical
+barline height that the engine should expect.
+
+For a multi-line staff, any barline is expected to go from the top staff line to the bottom staff line.
+But what if the staff at hand is a 1-line staff? This is no upper line or lower line.
+So, how far should a barline go above and below the single staff line?
+
+In our snippet example, we have two barlines, one at the center and one at the right side of the staff.
+They both go from roughly one head height above to one head height below the line.
+We use the notion of "head height" to replace the lacking notion of interline.
+These barlines thus have a height of about 2 "interlines".
+
+But let's consider this other example, with a 5-line staff and a 1-line staff: 
+
+![](../assets/images/drums_stave_sizes.png)
+
+The typical barline height for the 1-line staff is here the same as for the 5-line staff, that is 4 interlines.
+
+### Specifications
+
+Since the engine has no way to guess by itself the needed values of interline and barline height, we have to tell the engine which values to use for the image at hand.
+
+This can be performed via the ``Book | Set book parameters`` menu as follows:
+
+| Comment | Dialog |
+| :---    | :---:  |
+| 0/ Initial dialog,<br> by default the engine expects standard 5-line staves  | ![](../assets/images/fandango_params_initial.png) |
+| 1/ The 1-line switch has been selected,<br> the "Barline height" field appears | ![](../assets/images/fandango_params_1line.png) |
+| 2/ Barline height set to "two" interlines | ![](../assets/images/fandango_params_barline_height.png) |
+| 3/ No multi-line staff in image,<br> the "Interline" field appears    | ![](../assets/images/fandango_params_interline.png) |
+| 4/ Final dialog content   | ![](../assets/images/fandango_params_final.png) |
+
+Regarding the "Barline height" field, the dialog prompts for a value among four possibilities:
+- ``four``: This is the default value of 4 interlines, as seen on typical standard staves.
+The other possibilities can apply to 1-line staves only.
+- ``twoThenFour``: Barlines are 4 interlines high, except a half-size for the starting barline (either 2 above or 2 below)
+- ``two``: All barlines are 2 interlines high, as in our snippet example.
+- ``oneThenFour``: Barlines are 2 interlines high, except a half-size for the starting barline (either 1 above or 1 below)
+
+Regarding the "Interline" field, it appears when we explicitly tell the engine that there is no standard 5-line staves, and thus there are only 1-line staves in the image.
+Hence the need for the user to enter an interline value.  
+We have to measure the typical height of a note head or half the typical height of a barline.
+We can do so by drawing a lasso either in the Binary tab, or in the Data tab (once the Pixel board has been opened).  
+This gives about 31 pixels for our snippet example.
+
+### Transcription
+
+Once the book parameters are correctly set, the snippet gets perfectly transcribed.
+Here is the final result using the MuseScore plugin:
+
+![](../assets/images/fandango_musescore.png)

docs/index.md

@@ -7,16 +7,20 @@ nav_exclude: true
 ## For the end user
 
 - [HandBook](_pages/handbook)  
-General user documentation  
-Now available in web and PDF versions
+This is the general documentation, meant for the end user.  
+It is now available in two versions:
+    - A web version (what you are reading)
+    - A PDF version (downloadable via the button below)
+
 {: .d-inline-block }
 new
-{: .label .label-yellow }  
-[Download PDF file](https://github.com/Audiveris/audiveris/releases/download/{{ site.audiveris_release }}/Audiveris_Handbook.pdf)
+{: .label .label-yellow }
+
+[Download the PDF version](https://github.com/Audiveris/audiveris/releases/download/{{ site.audiveris_release }}/Audiveris_Handbook.pdf)
 {: .btn .text-center }
 
 ## For the developer
 - [Format of ".omr" files](_pages/outputs/omr)  
-Description of the internals of any ".omr" Audiveris book file
+This is the description of the internals of any ``.omr`` Audiveris book file
 - [Audiveris Wiki](https://github.com/Audiveris/audiveris/wiki)  
-Articles about the development and potential evolutions of Audiveris project.
+This Wiki gathers various articles about the development and potential evolutions of the Audiveris project.