Deploy preview for PR 114 🛫

pr-preview/pr-114/.gitignore

@@ -0,0 +1,2 @@
+.idea
+.DS_Store

pr-preview/pr-114/CNAME

@@ -0,0 +1 @@
+plaine-and-easie.info

pr-preview/pr-114/EDITORIAL.md

@@ -0,0 +1,204 @@
+## Plaine & Easie Specification Editorial Process
+
+The editorial process is designed to capture the process and discussion behind changes to the specification, promote
+transparency, and preserve an audit trail for the historical development of the specification in response to feedback.
+
+The process is divided into three main activities:
+
+1. Reporting an issue, or requesting a change, through the Issues section of this repository. Discussion may follow
+to clarify the scope of a change, or to present alternate courses of action.
+2. A Pull Request against the text of the specification enacts the change. The changes may go through several revisions, 
+and the history of those revisions are captured in the Pull Request.
+3. Approval by the Editors and merging the Pull Request. At least two approvals by the Editors, not including the author 
+of the Pull Request, is required to merge a change. Once a change has been merged, it is part of the specification.
+
+Each of these steps serves to document the reason for the change and the person who requested it, the various iterations 
+and discussions the change has gone through, and then a record of the approving editors who accepted the change. 
+
+More details about each of these steps follows.
+
+### Issue Reporting
+
+Individuals who have identified a change they wish to see should start by opening an issue on this repository. Please
+do not open Pull Requests to enact a change without first having an issue describing it. In your issue, provide as much
+detail as possible about the motivation for the change. Concrete use cases are extremely helpful for understanding 
+motivation.
+
+### Pull Requests and Revisions
+
+Once an issue has been described, a member of the Editors, or a community member on invitation from the Editors, can 
+open a pull request to make the changes to the specification. We use [ReSpec](https://respec.org) as the tool for 
+presenting the specifications; see the section below on how ReSpec works. Each Pull Request should limit itself to 
+solving one or, at most, two related issues. Editors other than the original author of the Pull Request can ask for 
+further changes.
+
+### Merging and Approval
+
+By convention, the original author of the pull request cannot approve their own change. Once a change has been approved
+by two other editors it may be merged into the specification. The last approving editor also does the merge. 
+
+There are two options open to editors for reviewing a pull request.
+
+ 1. Approve. The Pull Request is approved without any further changes needed.
+ 2. Request changes. The Pull Request should be modified to include changes as described.
+
+To find these options, choose the "Files changed" tab on a Pull Request, and select the "Review changes" button.
+
+If an editor requests changes, then the Pull Request author should enact the changes, or try to convince the change
+requester that they are not necessary. The only way the change can move forward is if two editors have selected 
+"Approve" without any further changes needed.
+
+Once merged, the change becomes part of the history of the specification. Since we use the git version control system,
+these changes are preserved and the history of the changes comes "for free" with the system. Anyone can go back through
+the history log of the changes and see when a change was made. 
+
+When viewing a file, the "Blame" button at the top of the file will even annotate the whole code to show you who changed
+every section of the underlying HTML, and will link back to the pull request that initiated that change.
+
+Sometimes, if many changes have been introduced, a conflict may appear that will prevent merging. In this case it is
+up to the Pull Request author to clear the conflict and to ensure it can be safely merged.
+
+## Editorial Guidelines
+
+Prior to Version 2, the Plaine & Easie Code specification was written primarily for an audience of encoders;
+that is, people who were responsible for creating Plaine & Easie encodings when cataloguing sources in RISM. As such,
+it was a combination of specification and encoding guidelines, and had a number of under-specified, vague, or conflicting
+rules. In Version 2, these two purposes were separated into dedicated documents, and the specifications are now written 
+to provide a comprehensive set of the rules of the encoding scheme, while the guidelines build on the specification to 
+provide further assistance with encoding scenarios.
+
+Changes to the Version 1 specification should only be made to fix language or resolve ambiguity without changing the core
+encoding scheme. Since this is the most widely adopted form of the specification, and is used outside RISM, changes 
+to the scheme have knock-on effects for others.
+
+The Version 2 specification strives to provide unambiguous language for people who want an authoritative reference for 
+what is, and what is not, allowed in Plaine & Easie. In addition to assisting encoders by knowing what they can include, 
+it is also meant to serve as a reference for software developers and data scientists, to know what data they can expect 
+when building tools that use Plaine & Easie code, and to understand what constitutes "valid" or "invalid" data.
+
+When writing the specifications, it is important to keep in mind the concepts of "normative" and "non-normative". These
+terms refer to the style and content of the sections of the specification. In a normative section, the content should be
+written to set out the rules for a given component. To provide clarity, a restricted set of words drawn from 
+[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.txt) set out the parameters, and provide an easy way to identify the 
+core rules of the code. These words are spelled in all-caps in the specification.
+
+These words include:
+
+ - MUST / MUST NOT: A hard requirement or prohibition; violating this requirement results in invalid PAE.
+ - SHOULD / SHOULD NOT: Recommended; violations do not affect validity, but they may raise warnings.
+ - MAY: Optional.
+
+Non-normative sections, in contrast, are meant to provide additional context or to describe additional technologies
+without setting out a hard-and-fast set of rules for them. Non-normative notes may be included in normative sections,
+but normative content cannot be included in non-normative sections. The RFC 2119 words should be avoided in non-normative
+sections (the words themselves may be included, but not styled in upper-case).
+
+By way of example, a specification for a peanut butter sandwich might go something like this:
+
+    The sandwich MUST include two slices of bread, and MUST include peanut butter. Peanut butter SHOULD be spread evenly
+    across the surface of the bread. Peanut butter MAY be spread on both slices. After spreading, both slices MUST be
+    pressed together, and the peanut butter MUST be between the slices.
+
+    Non-normative note: Both crunchy and smooth peanut butter can be used to make a peanut butter sandwich. Some
+    implementations of peanut butter sandwiches also include other ingredients, such as jam or bananas.
+
+Although a somewhat trivial example, we can easily tell from these rules that the requirements for a peanut butter
+sandwich are:
+
+ - Two slices of bread
+ - Peanut butter
+ - Slices must be pressed together
+ - Peanut butter must be in the middle.
+
+Optionally, the peanut butter should be evenly spread (recommended, but there's no rule saying that it can't just be a
+blob in the middle), and optionally the peanut butter can be on both slices (it does not affect the nature of the 
+sandwich if it's on one or both slices).
+
+The non-normative note provides some additional context about the sandwich. It answers questions that do not affect
+the core specification (both crunchy and smooth are peanut butters, so we didn't need to specify this, but it may
+be a question that a reader might have).
+
+You will also notice that nothing is said about other forms of peanut butter sandwiches, like a single piece of
+bread folded over; In our scheme, this is an invalid form of sandwich because it does not meet the two-slice rule. 
+This is not to say that in the greater world this is invalid, but in our specific universe that we have constructed, it 
+is not a valid form of sandwich.
+
+To bring this back to Plaine & Easie, it is clear that we are not specifying how *all* music notation works, but we are
+only concerned with describing how it works within a limited context. So if we say that a clef MUST specify line numbers
+from 1-5, we are not saying that other forms of clefs on 6-line staves do not exist; we are simply saying that Plaine &
+Easie does not support it.
+
+### Style
+
+Spelling follows the US form of words (flavor, neighbor, digitize). Serial commas are used in lists. Titles of sections use headline case (Key Signature, not Key signature). Dates, if necessary,
+are given in YYYY-MM-DD form. Measurements are given in metric.
+
+Do not, except under specific circumstances, change font face, size, color, or other style features.
+
+### ReSpec and Markup
+
+The specification is written in plain HTML, but it uses [ReSpec](https://respec.org), a tool developed by the W3C, 
+to enhance and augment the plain HTML with additional functionality. Some examples of the additional things that ReSpec 
+does is to add notes that a section is non-normative, creates a table-of-contents for the sections, adds nicely 
+formatted front matter to the top with editors and other administrative information, among other things. These features
+are controlled by adding special CSS classes or IDs to the HTML elements, which then mark them to be processed specially.
+
+The easiest way to write ReSpec to get it to format it the way you want is to copy what has been done in previous 
+sections. The ReSpec documentation also provides examples of how you can mark some things up, but it is not exhaustive,
+so you may have to resort to trying something and seeing if it works.
+
+### Previewing Pull Requests
+
+When a pull request is opened, a GitHub action will publish the version of the specification so that others can preview
+how it looks. The URL will contain the number of the pull request in the URL. Subsequent updated to the pull request
+will also update the preview. 
+
+For example, https://rism-digital.github.io/pae-code-spec/pr-preview/pr-49/ will provide a preview of Pull Request #49.
+
+You can always find a link to the preview in the Pull Request itself.
+
+### Rendering Examples with Verovio
+
+At present, previewing Plaine & Easie code with Verovio within the specifications is possible. Rendering is only available
+within a table of examples. For example:
+
+```html
+<table class="simple" style="width: 100%">
+    <thead>
+    <tr>
+        <th>Code</th>
+        <th>Notation</th>
+    </tr>
+    </thead>
+    <tbody>
+    <tr class="notation-example">
+        <td class="notation-code">
+            <script type="application/json">
+                {
+                    "clef": "G-2",
+                    "keysig": "bBEA",
+                    "timesig": "4/4",
+                    "data": "{''6E'B8G}{GA}-''C{'3B8..G}"
+                }
+            </script>
+            <code>{''6E'B8G}{GA}-''C{'3B8..G}</code>
+        </td>
+        <td class="notation-result"></td>
+    </tr>
+    </tbody>
+</table>
+```
+
+The important elements about this markup are:
+
+ - The `notation-example` class on the `<tr>` element. This signals that the row contains some markup that should be
+passed to Verovio.
+ - The `notation-code` class on the `<td>` element. Within the `<td>` you should embed a script tag with a JSON-formatted
+Plaine & Easie document. This will be the format used by Verovio to render the example. It will not be shown to users.
+ - The `<code>` tags within the `notation-code` element are what will be shown to the users. This means you can restrict
+the example being shown to just the elements you are trying to illustrate, while omitting any additional code needed to
+render, but unnecessary for the example.
+ - The `notation-result` `td` must always be blank. The SVG output of the rendering will be placed in this cell.
+
+Any other `<td>` elements within the `<tr>` can be present, but will be ignored.
+

pr-preview/pr-114/README.md

@@ -0,0 +1,42 @@
+## Plaine & Easie Code Specification
+
+The Plaine & Easie Code is a text-based music notation encoding system, primarily designed to be used
+for encoding small, monophonic extracts from a larger musical composition. 
+
+The Plaine & Easie code system was first proposed by Barry S. Brook, with input from several others, in 1964, 
+as a means of capturing incipits for more precisely identifying musical compositions in manuscripts. Incipits were
+a means of uniquely identifying compositions that could not otherwise be uniquely identified by the title or composer
+of the work.
+
+Plaine & Easie code was used in the RISM cataloguing systems, first typewritten on index cards, and then in 
+software databases. In 2004 the Plaine & Easie code was [adopted](https://www.loc.gov/marc/marbi/2004/2004-05.html) as 
+part of the MAchine Readable Catalog (MARC) standard. Currently, the RISM uses Muscat as its cataloguing system which
+has Plaine & Easie support integrated.
+
+RISM now holds well over 1 million incipits encoded using the Plaine & Easie code; a significant corpus of notated music
+and an impressive global effort. These incipits have been the subject of a number of tools, databases,
+and studies, and with an increasing number of software tools and projects using it, further improvements and enhancements
+to the code, and to the documents that describe it, were felt to be necessary. In some areas, the lack of clear specifications,
+or inconsistent behaviours, have made it challenging for ensuring consistency across the whole corpus, which in turn
+made it difficult to build data authoring and validation tools. 
+
+This repository hosts two different versions of the Plaine & Easie Code specification. The first, which we are calling
+"Version 1", represents the status of the code as it was until 2022. We have decided to forego any significant changes
+to this version of the specification, as it represents the most widely adopted form of the code, and changes to this
+specification would risk introducing confusion.
+
+The second version, "Version 2", represents work-in-progress for changes to the Plaine & Easie Code. These changes are
+largely based in the goal of making the Plaine & Easie Code more consistent, such that the large existing corpus of 
+incipits can be more easily used in notation search, data analysis, and data science.
+
+
+### References
+
+Brook, B., et al. 1964. Notating music with ordinary typewriter characters (A Plaine and Easie code system for Musicke). 
+_Fontes Artis Musicae_ 11 (3). pp. 142–159.
+
+Brook, B. 1965. The simplified "Plaine and Easie Code System" for notating music: A proposal for international adoption. 
+_Fontes Artis Musicae_ 12 (2/3). pp. 156–160.
+
+MARC Development Office. 2004. Proposal No.: 2004-05, Changes needed to Accommodate RISM Data -- Music Incipits. 
+https://www.loc.gov/marc/marbi/2004/2004-05.html

pr-preview/pr-114/bare_pr_preview/HEAD

@@ -0,0 +1 @@
+ref: refs/heads/main

pr-preview/pr-114/bare_pr_preview/config

@@ -0,0 +1,6 @@
+[core]
+	repositoryformatversion = 0
+	filemode = true
+	bare = true
+[remote "origin"]
+	url = https://github.com/rossjrw/pr-preview-action

pr-preview/pr-114/bare_pr_preview/description

@@ -0,0 +1 @@
+Unnamed repository; edit this file 'description' to name the repository.

pr-preview/pr-114/bare_pr_preview/hooks/applypatch-msg.sample

@@ -0,0 +1,15 @@
+#!/bin/sh
+#
+# An example hook script to check the commit log message taken by
+# applypatch from an e-mail message.
+#
+# The hook should exit with non-zero status after issuing an
+# appropriate message if it wants to stop the commit.  The hook is
+# allowed to edit the commit message file.
+#
+# To enable this hook, rename this file to "applypatch-msg".
+
+. git-sh-setup
+commitmsg="$(git rev-parse --git-path hooks/commit-msg)"
+test -x "$commitmsg" && exec "$commitmsg" ${1+"$@"}
+:

pr-preview/pr-114/bare_pr_preview/hooks/commit-msg.sample

@@ -0,0 +1,24 @@
+#!/bin/sh
+#
+# An example hook script to check the commit log message.
+# Called by "git commit" with one argument, the name of the file
+# that has the commit message.  The hook should exit with non-zero
+# status after issuing an appropriate message if it wants to stop the
+# commit.  The hook is allowed to edit the commit message file.
+#
+# To enable this hook, rename this file to "commit-msg".
+
+# Uncomment the below to add a Signed-off-by line to the message.
+# Doing this in a hook is a bad idea in general, but the prepare-commit-msg
+# hook is more suited to it.
+#
+# SOB=$(git var GIT_AUTHOR_IDENT | sed -n 's/^\(.*>\).*$/Signed-off-by: \1/p')
+# grep -qs "^$SOB" "$1" || echo "$SOB" >> "$1"
+
+# This example catches duplicate Signed-off-by lines.
+
+test "" = "$(grep '^Signed-off-by: ' "$1" |
+	 sort | uniq -c | sed -e '/^[ 	]*1[ 	]/d')" || {
+	echo >&2 Duplicate Signed-off-by lines.
+	exit 1
+}