Re: HTML documentation for latest MusicXML version?

Thanks, Karim and James. I have written this up as issue 353 (https://github.com/w3c/musicxml/issues/353 <https://github.com/w3c/musicxml/issues/353>). I have referenced Karim’s proof of concept and linked to several other possibilities for the tooling we could use for hosting the specification on GitHub in a way that works with a continuous integration setup.

The list of possibilities is just what I had in front of me at the time. I’m sure there are other options for both XSD-to-documentation conversion as well as tools for hosting documentation on GitHub. If anybody has favorite tools they would like us to consider, please add those in comments.

Best regards,

Michael Good
VP of MusicXML Technologies
MakeMusic, Inc.



> On Dec 8, 2020, at 1:35 AM, James Sutton <jsutton@dolphin-com.co.uk> wrote:
> 
> Hi Michael,
> 
> I would really like to see your excellent example pictures retained. (eg http://usermanuals.musicxml.com/MusicXML/MusicXML.htm#EL-MusicXML-schleifer.htm) <http://usermanuals.musicxml.com/MusicXML/MusicXML.htm#EL-MusicXML-schleifer.htm?TocPath=MusicXML%20Reference|Score%20Schema%20(XSD)|Elements|note|_____89)>. They are really helpful.
> 
> Thanks
> James Sutton
> Dolphin Computing
> www.seescore.co.uk <http://www.seescore.co.uk/>
> www.playscore.co <http://www.playscore.co/>
> 
> 
> 
> 
> 
>> On 8 Dec 2020, at 02:44, Karim Ratib <karim.ratib@gmail.com <mailto:karim.ratib@gmail.com>> wrote:
>> 
>> Agreed, would be great to track this in an issue. I'll let you create it, Michael, since you know best what you're looking for. I'll be happy to mention my experiment above, and to suggest some solutions going forward. I'd be grateful if you could subscribe or mention me in the issue.
>> 
>> On Mon, Dec 7, 2020 at 6:08 PM Michael Good <mgood@makemusic.com <mailto:mgood@makemusic.com>> wrote:
>> Hello Karim,
>> 
>> Thank you so much for this! 
>> 
>> I definitely want to get some documentation present for 4.0 so we can retire the 3.0 version. Ideally this would incorporate the extra material that is in the 3.0 spec, such as the tutorial, the musical examples, and the additional explanations.
>> 
>> It probably is time to write this up as an issue. We could then use that issue to collect some tooling alternatives such as xs3p / xsltproc, gitbook, and several other tools that specialize in either XSD-derived and/or GitHub-based specifications.
>> 
>> Best regards,
>> 
>> Michael Good
>> VP of MusicXML Technologies
>> MakeMusic, Inc.
>> 
>>> On Dec 6, 2020, at 1:09 PM, Karim Ratib <karim.ratib@gmail.com <mailto:karim.ratib@gmail.com>> wrote:
>>> 
>>> For what it's worth, I produced an HTML version of the MusicXML 3.1 XSD using a tool called xs3p and xsltproc. Although it's significantly simpler than the official (but obsolete) user manual, it has a number of advantages that I outline on a blog post at https://blog.karimratib.me/2020/12/06/document-musicxml.html <https://blog.karimratib.me/2020/12/06/document-musicxml.html>. The result is at https://blog.karimratib.me/musicxml.html <https://blog.karimratib.me/musicxml.html>.
>>> 
>>> If there's interest from the community here, we can enhance the XSLT transformation as needed, and automate the conversion process using a GitHub Action every time a change is made to musicxml.xsd. 
>>> 
>>> 
>>> On Fri, Nov 20, 2020 at 11:36 AM Karim Ratib <karim.ratib@gmail.com <mailto:karim.ratib@gmail.com>> wrote:
>>> I've been using https://usermanuals.musicxml.com/MusicXML/Content/MusicXMLReference.htm <https://usermanuals.musicxml.com/MusicXML/Content/MusicXMLReference.htm> as a browsable reference for MusicXML, but I notice it was last updated in 2015. Is there an up-to-date documentation site for version 3.1? https://w3c.github.io/musicxml/ <https://w3c.github.io/musicxml/> does not seem to include the full documentation - only changes.
>>> 
>>> If it's not available anywhere, and given some interest from the community, I'd be happy to engage in standing up a site generator for the latest version that can be kept updated with GitHub commits.
>>> 
>> 
>