|
|
@@ -54,11 +54,11 @@ As the top of the file are these five metadata entries. We call them *metadata s
|
|
|
- melody
|
|
|
- structure
|
|
|
|
|
|
-As for the syntax, each line starts with the metadata string, followed by *": "*, and ends with a non-empty string that acts as the value of the metadata string, which we call *metadata value*. The `structure` is allowed only `R` and non-negative integers values separated by one comma each, which represents the structure or order in which to song is to be played by dividing the song into refrain and verses. The values in between the commas are called *structure elements*.
|
|
|
+As for the syntax, each line starts with the metadata string, followed by the string literal `: `, and ends with a non-empty string that acts as the value of the metadata string, which we call *metadata value*. The `structure` is allowed only `R` and non-negative integers values separated by one comma each, which represents the structure or order in which to song is to be played by dividing the song into refrain and verses. The values in between the commas are called *structure elements*.
|
|
|
|
|
|
Hence to check if a line in the header has the correct syntax use the following regular expression: `^(?!structure)\S+: .+|^structure: ([0-9]+|R)(,([0-9]+|R))*$`. What is not captured syntactically by this regex is that each metadata string and value pair must appear *exactly once* in the header.
|
|
|
|
|
|
-The semantics of the other metadata values can be pretty much whatever you want, as long as they adhere to the syntax. Note also that the arrangement of lines doesn't have to match the list above, e.g. the line with the book metadata string can be above the line containing the title metadata, but note that it is probably better to not mix this up anyway for quicker manual editing's sake.
|
|
|
+The semantics of the other metadata values can be pretty much whatever you want, as long as they adhere to the syntax. For practical reasons it is still recommended to adopt guidelines e.g. the use of consistent naming of song books and page numbering in a given song repository. Note also that the arrangement of lines doesn't have to match the list above, e.g. the line with the book metadata string can be above the line containing the title metadata, but note that it is probably better to not mix this up anyway for quicker manual editing's sake.
|
|
|
|
|
|
Example of a metadata header:
|
|
|
|
|
|
@@ -70,7 +70,7 @@ Example of a metadata header:
|
|
|
|
|
|
#### 2. Part: The Text Body
|
|
|
|
|
|
-To start off with the syntax, every unique structure element, will be placed on a separate line between an opening square bracket directly to the left and an closing square bracket directly to the right, e.g. `[R]` or `[3]`. We call these lines *structure element identifiers*. After each of those lines must follow a finite amount of lines that semantically carry the song text of the corresponding refrain or verse indicated by the structure element. The lines which are empty or only contain whitespace after the last line that doesn't meet these two requirements before either the next structure element identifier or the end of the file are *ignored*, while the lines that are empty or only contain whitespace before that last line who doesn't meet these two requirements are *not ignored*, as they semantically could act as separators intended by the user. Note that such ignored lines are not syntactically necessary, but are heavily encouraged for their clearer separation they provide semantically.
|
|
|
+To start off with the syntax, every unique *structure element*, will be placed on a separate line between an opening square bracket directly to the left and an closing square bracket directly to the right, e.g. `[R]` or `[3]`. We call these lines *structure element identifiers*. After each of those lines must follow a finite amount of non-empty lines that a) semantically capture the song text of the corresponding refrain or verse indicated by the *structure element* and b) syntactically contain at most the amount of characters specified in the config as `METADATA_VALUE_CHAR_LIMIT` which by default is set to `100`. The lines which are empty or only contain whitespace after the last line that doesn't meet these two requirements before either the next *structure element* identifier or the end of the file are *ignored*, while the lines that are empty or only contain whitespace before that last line who doesn't meet these two requirements are *not ignored*, as they semantically could act as separators intended by the user. Note that such ignored lines are not syntactically necessary, but are heavily encouraged for their clearer separation they provide semantically.
|
|
|
|
|
|
Here is a example of a text body using the first three verses of *'Amazing Grace'* written by John Newton found on [Hymnary.org](https://hymnary.org/text/amazing_grace_how_sweet_the_sound):
|
|
|
|
