This is the 2021 version of the OpenSoundControl website. It combines legacy OSC website content (especially including the 1.0 Specification) with the bare-bones implementation of Matt Wright's CCRMA Documentation and a way for people to contribute content that editors will moderate/curate/organize/publish.
The auto-generated list of pages and table of contents are one of the best ways to find information on the site.
The source files use the Markdown format. There are lots of great Markdown guides, tutorials, cheatsheets etc. Also the Pandoc manual has lots of great info about Markdown in general and Pandoc's extensions to Markdown in specific.
Every .html file comes from a corresponding .md file that you can
also download; for example this file README.md generates
the output README.html.
The site's repo contains bash scripts to build the website html with pandoc, deploy to the webserver, and build the overall table of contents.
Part of the simplicity of these scripts is based on limiting assumptions about the structure of the source markdown files, especially in the creation of the site's page list and table of contents:
- all headings must use the markdown syntax with some number of
#at the beginning of the line (not the line of---on the next line). - every file must contain at least one top-level (
#i.e., HTML<H1>) - the "nesting structure" of the headings must be "well formed", e.g.,
you can't go from
#(H1) to###(H3) without##(H2) in between. - Can't use pandoc metadata blocks for pages' title, author, and date, because that would mess up the incredibly simple navigation menu system.
- All within-site links must be relative URLs (starting neither with "http" nor with "/" but rather just the name of the html file with maybe a "../").
Here are some of the values and goals embodied in this project:
- Simple, clear documentation oriented towards both beginngers ("what is OSC? / "how do I use it?") and experts (implementors, developers, etc.)
- Simple, clean, accessible web design, not flashy / graphics-rich
- Clear and useful site navigation supporting discovery of curated useful information
- Central location aspiring to link to "all" the world's information about OpenSoundControl
- Mechanism for the OSC community to contribute site content so it stays up do date.
- The site is for publication, not discussion. In other words, it's a long-term site containing curated information intended to be useful in the future, not a discusison forum such as slack / twitter / reddit / stackoverflow. (If something like this takes off, we would link to it from this site.)
- Not a tech support help desk; more of an unstaffed reference library
- Slow publication cycle, easy to maintain (by volunteers hoping to spend ~1-2 hours/month)
- Weak preference for the serial comma
- Source content stored in simple files in a version control repository (that tracks history), not some software's internal database
- Never have email addresses on the site or in the site's back-end repo
- Simple, lightweight open-source toolchain; not tied to any "heavy" infrastructure such as Drupal.
- Source data (in .TSV and .md files) automatically become the site's html files; html is built locally and not committed to the repo
- Designed for long-term maintainability with potentially infrequent updates
- Designed to be easy to migrate site content to another platform in the future
- Imposes some limits on markdown use to make the scripts easier to implement
- Nothing set in stone: any aspects of the implementation are open to improvement.