Hmm, I can understand why you'd want to remove Gem if it isn't cross-platform yet, but what's wrong with the reference section? In my experience, that's typically one of the most important sections for new users when they start discovering the built-in objects.

A bit of an oversight. I just tried to remove things that could look broken to users.

I could probably move it further up and give it a more meaningful title like "Internal Objects"

Well, the rationale behind what I did with the first few sections is that I tried to make it look familiar to vanilla and extended users, so that they will find their way. This might not be perfectly noob-friendly, but my take is that we should try to cater to both audiences -- noobs and long-time Pd users. Therefore the "Reference" title. That way the first five sections will be recognizable immediately by the long-time users through the titles alone, because that's what they have in the vanilla Pd Help browser under "Pure Data", while noobs can still figure out what it's all about by reading the descriptions below the title. I think that it's a reasonable compromise.

FWIW, here's what I use for that section in my release branch now:

    {
        id: "doc/5.reference",
        title: "Reference",
        description: "help patches for all built-in object classes"
    },

Otherwise, I'm using your menu now in the release branch, only added the DISIS and Gem sections back in since they're important on Linux IMHO.

Sorry for being so picking about the help stuff. :) But I think that it's really important if we want to make ppl switch from extended and vanilla, so that they find all the docs that they've learned to rely on. That's one of the things that really threw me off when I first started using purr-data -- I just couldn't figure out how to get at the basic help patches that I knew must all be there.

Ok, I added "Reference" back with fde50f6d

I want to be a stickler about non-portable libs, though. Things need to run and make sense on all platforms, otherwise it's a major usability regression. That probably applies to PDDP image tutorial, too, since it relies on Gem.

Things need to run and make sense on all platforms, otherwise it's a major usability regression.

I understand. Yeah, the PDDP Image tutorial is all about Gem, so it should then be removed as well.

I'd still like to keep these in my release branch which I use to build the Linux packages. Linux users who have been using Pd-Extended and -L2Ork before will look for those. But if you think that this is a problem, I can also remove them there.

We could probably get DISIS building on all platforms, at least with a wrapper for disisi_wiimote.

Gem is really a resource drain atm. I've pinned the old Pd-l2ork version in this repo because HEAD on Linux at https://github.com/umlaeute/Gem.git will segfault when creating [gemwin], or probably any Gem object. (Nor can I build the most recent version tag without segfaults.) Even the current code does something fishy when it loads-- see issue #138 (closed). And probably 50% of the total build time is devoted to building Gem.

Matt Barber also reported that there are lots of problems when trying to get it to compile at all on OSX.

We should probably keep the docs synchronized-- I can add the Gem-based ones back if necessary. But we also need to somehow communicate to users that the situation is dire because none of the devs can currently get Gem building as a 64-bit lib on OSX.

I've pinned the old Pd-l2ork version in this repo because HEAD on Linux at https://github.com/umlaeute/Gem.git will segfault when creating [gemwin], or probably any Gem object.

Yeah, I noticed this too a while back. I understand that maintaining Gem support in Pd-L2Ork/Purr-Data is a chore. But it's currently the only way to get 3d graphics and video playback in any Pd flavor, and media artists really want that kind of stuff. Of course, we might also offer it as a kind of Pd-L2Ork addon package. Ico will probably dislike the idea, since he wants all batteries included. But Gem is such a big package that it makes sense to build and distribute it separately IMHO.

I'd really like to see that functionality being replaced one day by a cross-platform implementation using HTML5 embedded media and WebGL (if nw.js supports those). But at least the WebGL support is probably going to be a big project in itself. And then there's of course the problem with legacy patches that just need Gem to run. Do you have any thoughts on this?

We should probably keep the docs synchronized-- I can add the Gem-based ones back if necessary.

Well, it's not really a big deal, I can live without having them in the toc if it makes you happy. But couldn't we at least keep the DISIS section? (Could go under Externals, that's where I currently have them in my release branch.) Ico would surely appreciate to have those readily available to his students. ;-)

I'd really like to see that functionality being replaced one day by a cross-platform implementation using HTML5 embedded media and WebGL (if nw.js supports those). But at least the WebGL support is probably going to be a big project in itself.

It's all there in nw.js, and in any modern GUI toolkit for that matter.

The difficulty comes if there's a requirement that Pd be able to query the GUI toolkit for webgl data. Then there are two problems: a) round-trip latency from call to callback, and b) finding a suitable async message-passing interface when the rest of Pd is synchronous.

And then there's of course the problem with legacy patches that just need Gem to run. Do you have any thoughts on this?

The only option is to continue shipping it. If we made it an "add on" it would get even less attention than it gets now and bit-rot more quickly.

The only option is to continue shipping it. If we made it an "add on" it would get even less attention than it gets now and bit-rot more quickly.

Ok, but then it should also be visible IMHO, and that means adding it to the toc. :)

If I understand you correctly, your main issue with this is that Gem isn't available on Mac (yet), so if the corresponding toc entries are visible on the Mac then users will complain that it doesn't work there. But that's easy to solve. We could add a quick check to display_toc so that only sections are shown whose directories actually exist. extra/Gem doesn't exist in the Mac app anyway, and doc/manuals/2.Image could be removed (or renamed) in the Mac package. Let me try to code that up and send you a pull request.

Merge request is ready.