Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MIDI-related terms in terminology section are not defined in the MIDI reference #244

Open
mjwilson-google opened this issue Sep 18, 2023 · 1 comment
Labels
class: substantive https://www.w3.org/2023/Process-20230612/#correction-classes status: ready for editing Enough information should be available to implement this change in the spec
Milestone

Comments

@mjwilson-google
Copy link
Contributor

mjwilson-google commented Sep 18, 2023

The terminology section (https://webaudio.github.io/web-midi-api/#terminology) currently says the following:

"The terms MIDI, MIDI device, MIDI input port, MIDI output port, MIDI interface, MIDI message, MIDI System Real-Time message and system exclusive are defined in [MIDI]."

In addition to lacking a definition of a "valid MIDI message" (#164), there are several other issues with this section:

  • "MIDI device" is not really defined in the MIDI specification, although the meaning could be inferred from the text
    • Proposal: This is probably ok to leave as-is
  • "MIDI input port" and "MIDI output port" are called "MIDI In port" (or sometimes "MIDI IN port") and "MIDI Out port" in the MIDI specification, and are first defined in terms of electrical diagrams which isn't how the terms are used in the Web MIDI specification
    • Proposal: Redefine these terms in the Web MIDI spec based on the definitions of "MIDI In port" and "MIDI Out port" defined in the MIDI specification
  • "MIDI interface" isn't really defined in the MIDI specification; there is a definition of the hardware interface but that is not how we use the term in the Web MIDI specification
    • Proposal: This is a bit trickier; we seem to use the term "MIDI interface" to refer to things the OS layer presents. So maybe we need to find different references for this term, or to define the term directly in the Web MIDI specification.
  • [DONE] "MIDI System Real-Time message" is written in various ways in the MIDI specification: "Real Time", "Real-Time", "System Real-Time", "System Real Time", and sometimes with "messages" attached and sometimes without; it seems like the version with the space ("Real Time") is more common than the version with the hyphen ("Real-Time")
    • Proposal: Let's make the linked term "System Real Time" since the MIDI specification chapter that talks about these messages doesn't have a hyphen. The Web MIDI spec only references these messages in one section, so it's not a large change.
  • [DONE] "system exclusive" is written "System Exclusive" in the MIDI specification
    • Proposal: Update the name to "System Exclusive" to match the MIDI spec
  • [DONE] Most of the definitions are not linked from the rest of the spec text
    • Proposal: Link the first usage of each term in each section that uses it (edit: actually, link all usages)
  • The MIDI spec link is out of date since midi.org changed their website
@mjwilson-google mjwilson-google added the class: editorial https://www.w3.org/2023/Process-20230612/#correction-classes label Sep 18, 2023
@mjwilson-google mjwilson-google self-assigned this Sep 18, 2023
@mjwilson-google mjwilson-google added this to the CR milestone Sep 18, 2023
@mjwilson-google mjwilson-google added class: substantive https://www.w3.org/2023/Process-20230612/#correction-classes and removed class: editorial https://www.w3.org/2023/Process-20230612/#correction-classes labels Sep 18, 2023
@mjwilson-google
Copy link
Contributor Author

Referring to other specs, it seems like it's probably better to link the definitions every time they are used instead of just the first usage in each section. That part can also be done right before applying for CR status.

@mjwilson-google mjwilson-google added the status: ready for editing Enough information should be available to implement this change in the spec label Sep 30, 2023
@mjwilson-google mjwilson-google removed their assignment Oct 15, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
class: substantive https://www.w3.org/2023/Process-20230612/#correction-classes status: ready for editing Enough information should be available to implement this change in the spec
Projects
None yet
Development

No branches or pull requests

1 participant