Toward documenting .mscx format?
As the .mscx file format for version 2.0 is rapidly approaching some stability, is the time come to work out a way to document it? (The usual distribution format is .mscz, but this is mainly a ZIPped version of .mscx)
I see two main reasons for that:
1) as a help to developers (both veterans and rookies)
2) as a tool for planning future extensions (possibly with forward compatibility in mind) and investigating possible weaknesses.
If the answer to this question is "yes" (which I do not take as granted), some other questions stem easily.
A) A formal definition or a "verbose" description?
Formal definitions may be consumed by software tools much more easily, but human languages are more, hmmm..., human! Both can be useful, but we will probably have to make a choice.
B) Which format to use?
As .mscx is XML, among formal definitions DTD is an obvious candidate, but good, old BNF may have its applications too. Other will certainly propose other candidates.
C) Are there tools for automatically generate at least a reasonably comprehensive starting point?
I googled a little bit and found surprisingly little in this area. The only free tools I found to generate a DTD from XML's are:
- DTDGenerator which is now very old (2001?) and can take only a single XML file as input
- Trang which may take a collection of XML as input
- XMLBeans' inst2xsd which also may take multiple XML files as input, but generate a Schema as output, rather than a DTD
Then there are some non-free solutions.
The only one I tried (the easiest to install and run) is Trang and it could not parse even a single, moderately complex .mscx file. It may be a limitation of the tool or it may point to some weakness of the format used by .mscx: another reason to investigate more, I believe.
Summary: I'm just throwing the stone, feel free to post your comments and amendments !
Thanks,
M.
Comments
let him who is without sin cast the first stone
SCNR
In reply to let him who is without sin by Jojo-Schmitz
I have a DTD generator - I will throw a recently generated MuseScore 2.0 mscx at it and see what it generates.
In reply to I have a DTD generator - I by ChurchOrganist
Certainly worth a test run!
Do you mean the DTDGenerator I quoted above? In this case, the fact that it accepts only a single XML file as input makes somehow more complex to arrive at a reasonably comprehensive grammar.
Thanks,
M.
In reply to *That* DTDGenerator? by Miwarre
No I use XMLPad which will generate both DTDs and other Schemas
Attached is the result from a specially written file.
Perhaps a starting point?
I'm also attaching the MuseScore mscx file which XMLPad generated the DTD from.
Oh well, I should have known... Of course, my Linux distro already has an XML=>DTD tool, under the arcane command name
mkdtdskelin the rather cryptically namedlibxml-dt-perlpackage.Anyway, running a quickly-and-dirtly made selection of 3 of my .mscx through this tool generated the attached .DTD.
I am not familiar enough with DTD to tell if it make any sense or not and if it is of any use or not; possibly someone with more knowledge may help. The output file has a lot of comments which do not improve readability; they can probably stripped with some appropriate grep.
So, it seems there are ways to try, after all... Comments, suggestions and proposals are always welcome!
Thanks,
M.
...for your sample DTD. I assume you use WMHelp XMLPad (there are several XMLPad's around...), which seems powerful, but only runs under Windows (and iPad...). From the little descriptions I could find, it is not clear if it accepts multiple XML files as input for the DTD / Schema generation.
This is rather important, as the completeness of the resulting definition depends upon the completeness of the XML input. So, either:
The second way seems to me more flexible, as individual .mscx can be updated separately when a score file feature is modified or expanded and new, small, .mscx can be added for new features.
In the meantime, if anybody is interested (well, peoples do not seem crowding on this topic...), I have grep-ped my previous sample DTD to remove the comments, to improve readability (and to add an <?xml > tag, which is useful for syntax highlighting but not correct, as DTD's are not XML!).
Ciao,
M.
In reply to Thank you , Michael by Miwarre
I'm not sure DTD is the best way to start on this issue. DTD is perfect to validate an XML file with a computer program but it's not really useful as a documentation. As stated by Miwarre in the top post, the goal is not to have other programs reading MuseScore format but document the format to help new MuseScore developers, find weakness and plan future extensions.
Most of the element in the MSCX inherit from Element in the source code. So most of them have a write(properties)/read(properties) methods. It could be easier to parse the code to find these methods and derive a text or markdown document listing possible children tags from there. The less easy part is to document every element and attribute of course...
In reply to I'm not sure DTD is the best by [DELETED] 5
Indeed Nicolas, if you are not used to inerpreting DTD files then they are not the easiest things to follow.
I think maybe what we need is a hierarchical document written in something like pseudocode.
A DTD will be a good starting point to producing this, however.
I think maybe we need to produce a set of MSCX files each featuring one of the structures used.
I'm still pretty busy with the Jeux soundfont adaptation, but would probably have time after Easter to do some work on this.