In Max 5 I was working on a lot of reference and tutorial material in Max's unique XML format for a new object. To do that I basically copied the Max 5 "docs" folder and manipulated the appropriate files to my liking. It worked very well in Max 5.

Up to now I do not own Max 6 myself but was told that all my references and tutorials are not working anymore. I plan to have a closer look at it soon but like to know in advance:

Is there a simple way to make it work again?

Did C74 release an SDK or some kind of manual for creating Max XML documentation in the meantime?

Is there a simple way to make it work again?
What changes were made?
Did C74 release an SDK or some kind of manual for creating Max XML documentation in the meantime?

reference-xml-not-compatible-with-max-6-anymore

Have you ever got an aswer on this request? I'm having the same problem with my old max 5 xml references and there are no tutorials to help on how to vreate new documentations on my objects.

No, I never got any answer on this. But I figured it out on my own, eventually.

I never got down to the bottom of the entire Max documentation because that would have involved figuring out the Max XML syntax in its entirety. And even Cycling seem to use their own dedicated tool that just fills their XML files with content from another place/database. But I got my object's original Max 5 documentation working again. I am not too sure anymore but I think I did not have to change anything relevant in the reference (and tutorial) file headers. While Max 5 at startup seems to crawl through its search paths to index documentation files, Max 6 comes with two files that hold all meta information about the documentation, i.e. reference files, tutorial files (not patchers), vignettes, etc. So, you will have to add some information there, as well.

The two files are: obj-qlookup.json, which lists all objects in form of an XML lookup table, and doc-qlookup.json, which does the same for documents. Both files reside inside the /Cycling 74/Interfaces folder (on a Mac, don't know about Windoze).

The files are quite readable and pretty self explanatory, just stick to the syntax. Besides the brackets keep an eye especially on the commas. Missing a comma or putting a comma in the wrong place makes the whole documentation unusable!

obj-qlookup.json: It's a good thing to put your object(s) into a suitable object category. Doing so makes them easy to spot in the documentation Objects tab and also in the object palette. The thing I did not figure out is the "module" tag. There is also some "module" stuff going on inside the /patches/docs/refpages folder. I tried to mess around with it for a while but figured I did not need it in the end. The price is, I guess, that I cannot have my own refpages folder and have to use the existing max-ref, msp-ref, etc. folder hierarchy. But I can live with that.

doc-qlookup.json: Be sure to put your files inside the correct tags. There are tags like refpages for reference files which branches down into msp-ref, max-ref, etc. The content of a "digest" tag is shown in the documentation Objects tab and search results, maybe elsewhere as well – I did not check further than that. Then there is also a tutorials tag in case you wrote your own tutorials. I was not so sure about its "name" and "title" tags, so I just filled in the same text to be on the safe side.

I guess everybody reading this with the intent to try it at home will already know the dangers ahead. But anyways, here comes the disclaimer: **** Messing around with these files could seriously damage your Max 6 documentation. *** So keep backup copies in case anything goes south!

What's left to say...? Well, I hope someday in the near future we will see Cycling revealing the real magic behind all of this. Maybe even giving out their/some tool to create the documentation in a friendly way. I think 

 would benefit from that, users, programmers, Cycling. What is especially very very bad, is that you cannot combine two 3rd party documentations unless you get the users to do some handiwork themselves. So, if anyone with some more reverse engineering talent than me figures out how to add your own object documentation without needing to overwrite original files, I'll send you flowers. Or a toggle. Or a bang.

What's left to say...? Well, I hope someday in the near future we will see Cycling revealing the real magic behind all of this. Maybe even giving out their/some tool to create the documentation in a friendly way. I think EVERYONE would benefit from that, users, programmers, Cycling. What is especially very very bad, is that you cannot combine two 3rd party documentations unless you get the users to do some handiwork themselves. So, if anyone with some more reverse engineering talent than me figures out how to add your own object documentation without needing to overwrite original files, I'll send you flowers. Or a toggle. Or a bang.

By the way, I wrote my documentation for the note~ project which consists of four objects with help files and references, as well as ten tutorials. You might want to check it out if you like to see in detail what I did: www.noteformax.net. Thomas, the programmer, built an installer app which puts all files into the right place, but there is also a manual installation available.

A small comment for those who do Max 5 ref. docs: I noticed that many people, when it comes to ref. docs, they just simply make a 'docs' folder (BTW, usually they put this folder in the Cycling '74 folder instead of the original patches folder) and put their XMLs etc. there. While this seems to work fine at first, it actually messes up some of the cross references that one might want to put into their XMLs (like the 'see also' features etc.) To actually have everything working as expected, one has to copy the reference XMLs into the original folders (patches/docs/refpages on Mac OS) and add entries for each newly added XML in the appropriate _c74_contents.xml files of the respective folders.

The installer for the note~ project is a bit problematic. It overwrites the qlookup files, which means that when the next version of Max is released and then one installs note~ that it could break Max or parts of it that have changed.

Also, if every third-party takes this approach then every third-party installer will break every other third-party installer. Since we all need to live with each other in harmony this approach is not ideal.

As I both work for Cycling '74 and participate in third-party activity ( e.g. 

 among others) I have a vested interest in the way that documentation is rendered and is available for expansion by third-parties. With Tap.Tools I have had many fits and starts with trying to make reference pages work in Max 6 ( even with the supposedly inside information!). I know it is extremely frustrating.

The next version of Max will support some much needed improvements to assist in this area, including support for multiple obj-qlookup files that can be used for exposing your objects to the Explorer. Rendering of pages in the Documentation window is still problematic, however, because of the sandboxed AJAX infrastructure which must rely on the master qlookup files (randome directly listings on a user's system are forbidden in the AJAX world). The next version of Max does, however, offer a workaround: you can turn off the Max 6 AJAX rendering and use the older Max 5-style rendering of refpages. No it's not ideal. But given the size of the challenge it's a least a small step.

I suspect this won't assuage everyone from wanting to expose their refpages via qlookup modification. It might be worthwhile for third-party devs to come up with a standard way to "install" stuff to the qlookups. Maybe a script of some sort that can be executed as post-flight stage of a Mac installer and use regular expressions to smartly insert or update the files. If it were a project on Github I would anticipate there being several interested contributors.

The installer for the note~ project is a bit problematic.  It overwrites the qlookup files, which means that when the next version of Max is released and then one installs note~ that it could break Max or parts of it that have changed.

Also, if every third-party takes this approach then every third-party installer will break every other third-party installer.  Since we all need to live with each other in harmony this approach is not ideal.

As I both work for Cycling '74 and participate in third-party activity ( e.g. http://electrotap.com among others) I have a vested interest in the way that documentation is rendered and is available for expansion by third-parties.  With Tap.Tools I have had many fits and starts with trying to make reference pages work in Max 6 ( even with the supposedly inside information!).  I know it is extremely frustrating.

The next version of Max will support some much needed improvements to assist in this area, including support for multiple obj-qlookup files that can be used for exposing your objects to the Explorer.  Rendering of pages in the Documentation window is still problematic, however, because of the sandboxed AJAX infrastructure which must rely on the master qlookup files (randome directly listings on a user's system are forbidden in the AJAX world).  The next version of Max does, however, offer a workaround: you can turn off the Max 6 AJAX rendering and use the older Max 5-style rendering of refpages.  No it's not ideal.  But given the size of the challenge it's a least a small step.

I suspect this won't assuage everyone from wanting to expose their refpages via qlookup modification.  It might be worthwhile for third-party devs to come up with a standard way to "install" stuff to the qlookups.  Maybe a script of some sort that can be executed as post-flight stage of a Mac installer and use regular expressions to smartly insert or update the files.  If it were a project on Github I would anticipate there being several interested contributors.

indeed the note~ solution is lame. it messes with your directory and then gets abandoned whenever you update max6 anyway. however this is not really the fault of note~. it is the fault of cycling74 to fail to provide a proper documentation api.

it is fantastic tim took time to comment on this and mention possible 'solutions'. and i appreciate that. i am very pleased that a future version of max6 will support multiple obj-qlookup files. however the ajax issues will remain, and asking an end user to move to a version 5 style documentation system seems backward.

whilst a third-party 'club' on github is an idea to standardise workarounds, it smacks of disaster, and papers over the problems. the max sdk is so damn good, why fail with the documentation api? it is so so so important, and if the current ajax system cannot support third-party integration, then that should be considered a huge bug and it should be rewritten so that it does support it.

Of course we have been aware of the problems with the note~ installer. That is why we also offered a manual installation including a manual of how to update the json files in order to allow the installation of note~ together with other 3rd party objects with a max6-style documentation. For the installer I was simply hoping that minor Max updates would not change the lookup files and so far everything stayed the same (as far as I can tell). Anyway, multiple obj-qlookup files will at least solve the problem for us. Thanks for that.

It seems that the new Max version now supports multiple obj-qlookup files but not multiple doc-qlookup files?

The system is complex and 6.0.7 is one step in a transition. You are correct that multiple doc-qlookup files are not supported. Multiple obj-qlookup files are now partially supported in Max 6.0.7. I'll explain...

The documentation rendering (unless you change the new setting in your Max 6.0.7 preferences to turn off the new-style rendering) relies on both obj-qlookup and obj-doclookup. The documentation system still does not support multiple obj-qlookup.

Everywhere else the obj-qlookup is used does support it. This means that you can now provide icons for your objects in the Object Explorer, assign them to categories in the Object Explorer, etc.

The system is complex and 6.0.7 is one step in a transition.  You are correct that multiple doc-qlookup files are not supported.  Multiple obj-qlookup files are now partially supported in Max 6.0.7.  I'll explain...

The documentation rendering (unless you change the new setting in your Max 6.0.7 preferences to turn off the new-style rendering) relies on both obj-qlookup and obj-doclookup.  The documentation system still does not support multiple obj-qlookup.

Everywhere else the obj-qlookup is used does support it.  This means that you can now provide icons for your objects in the Object Explorer, assign  them to categories in the Object Explorer, etc.

I have same problem as Andrea Agostini describes in an other post (

https://cycling74.com/forums/explorer-autocompletion-and-basic-attributes-in-max6),

Multiple obj-qlookup doesn't seem to work for me.

Hello,
I have same problem as Andrea Agostini describes in an other post (https://cycling74.com/forums/explorer-autocompletion-and-basic-attributes-in-max6),
Multiple obj-qlookup doesn't seem to work for me.
What's the tricks ?
Best, eliott.


Reference XML not compatible with Max 6 anymore?