Examples/Pages that are better stored/edited on Disk

[mscuthbert]

I'm in awe of how well @adrianholovaty 's docgenerator is working for MusicXML (and it seems like for MNX also...)

One update I think is needed for musicxml is to move the larger schema documents like musicxml.xsd, note.mod, to31.xsl, partwise.dtd, and sounds.xml out of the json file and instead have the json file and Django store the filepath of the schema files and probably a header and footer for transforming them to HTML.

I was finding that I needed to make two changes--to JSON and to the schema files--in order to make a change to the documentation. A slight discrepancy in the docs (a space here, a comma there) vs. the spec if no big deal, but a discrepancy between docs and spec for syntax could be a major bug.

My guess is that the model would just need to be something like:

class SchemaFile(models.Model):
     # standard stuff
     header = ...TextField()  # that gets super cooly monkeypatched
     filepath = CharField() or Textfield()  w/ validator(filenotefound)
     footer = ...TextField()
     fileType = CharField()  # just in case we need different layout serialization, etc...

I'd be glad to help with this. Though now that MNX isn't XML-oriented, I want to say again that I think docgenerator might be better as a separate w3c-music-notation project that can be imported as a submodule and developed separately, so that the musicxml repertory could be pinned to a specific minimum (or maximum) version of docgenerator, and releases there could be separated from the MNX release standards.

[adrianholovaty]

It's been a while since I looked at the way the MusicXML docs system stores this data!

Looks like the schema documents are stored as "static pages", and all the markup is XML-escaped:

The "static page" system is meant to be a general-purpose, lightweight way of adding ad hoc pages to the documentation. When we were originally adapting the MusicXML docs to this system, I think we just decided this would be the fastest and easiest solution for the schemas.

I'd be totally fine with moving these out of the DB and into standalone files. There's already a media directory for storing stuff that's not in the DB, and I'd suggest we put the spec files in there. I believe that would give us the benefit of being able to link to the spec file directly (i.e., a raw XML document).

At the moment, the left sidebar of the MusicXML docs links to the specs:

...and each one of those files is displayed with the docs HTML wrapper:

Is there any benefit to keeping those HTML versions? I'd actually be tempted to remove them and simply change the left-sidebar links to go directly to the "raw" XML files. That'd save us from having to build a system to manage and render the schemas via Django (though that would be easy to set up).