Conditional logic in help topic files

Unfortunately, we don't want to expose translators and documentation authors to PHP, so actually changing it *within* the topic is not something that is going to happen with advanced help.

I think you can do what you want but you have to go back and rethink it; instead of making the logic inherent in the help, make the logic exist at the point where the help is injected.

What I would do is 'take over' about.html and provide all the PHP code you need there; introduce advanced help topics by choosing the topic you need and directly displaying it, along with any navigation you feel is necessary. This ends up being a layer between TinyMCE/your module and advanced help, but it allows the actual help files themselves to maintain their data integrity, while allowing you to display a specific portion of that help content with selections based upon permissions.

Does this make sense?

Using TinyMCE's about.htm file at the root of the help system raises some technical and usability issues which I didn't go into. But apart from that, with respect, I think you're mistaking an example of the problem for the problem itself. This is not about TinyMCE; it's about content management. Anybody will have the same problem I have if they need to design a help service whose content depends on the user's role, or on any other variable property.

I'm not sure what it would mean to "expose translators and documentation authors to PHP." If someone didn't know PHP, or didn't want to use it, they simply wouldn't use it. The module would otherwise work exactly as it does now.

Nevertheless, I wouldn't argue that allowing help file topics to be PHP files is the only way to meet this requirement. Anything that gives the designer reasonable control over help file content would work. For example, you might introduce a "pseudo-tag" that tests a variable or URL parameter and does "conditional compilation" of text. That would not be too different from rewriting the href and src tag properties based on "path:" and "topic:" prefixes.

You changed the title. =)

I'm not sure such a feature is truly desirable. Bear in mind that this system is modeled after the external help systems you'll find in windows and other packages, and these help systems can exist outside of the application itself. One reason that a strict no-php-minimal-processing system is in place is that we can, theoretically, put these files up on some drupal.org site and have them always, easily available, even without the application there. This particular use-case makes having logic inside the actual help file very risky.

Also, your use case with the system is slightly different; I think you're trying to provide end-user help. At the moment, advanced help is geared primarily toward Drupal system builder help. As an end-user tool it's currently poor, because it doesn't have any partitioning. Some amount of work would need to happen in order to add some form of partitioning before it could become an end user tool.

That said, I would still be very, very cautious of actually embedding logic, of any sort, within the help system itself. I think the idea that the help can exist completely external to the module or the site is an important one, and I really feel that providing your own interface to the help system is the best way to go about providing logic to choose which topics are shown.

First, let me say this: I know that by continuing this discussion I risk being invited to become a module developer myself. I'd be up for that, but I think I need a little more experience before I try it!

Bear in mind that this system is modeled after the external help systems you'll find in windows and other packages, and these help systems can exist outside of the application itself.

I can only repeat my previous response: designers won't have to use this feature if they don't want to. Designing a help system that can run standalone is a perfectly valid reason for not wanting to. But not every system needs that. In the case I'm looking at now, it not only isn't necessary, it wouldn't make any sense.

Also, your use case with the system is slightly different; I think you're trying to provide end-user help.

Not in the sense you probably mean. The help is for a couple of roles that perform administrative functions. You might say that they're intermediate between system builders and end-users. "Developer/end-user" is a continuum, not a dichotomy. For that reason, statements that a module is "for" a particular type of user tend to be slippery.

At the moment, advanced help is geared primarily toward Drupal system builder help. As an end-user tool it's currently poor, because it doesn't have any partitioning. Some amount of work would need to happen in order to add some form of partitioning before it could become an end user tool.

I'm not sure what partitioning means in this context, but I appreciate the argument that development objectives must be prioritized, and end-user features can only be added when the foundation for them has been laid. Perhaps we should continue this discussion after the next major version is released.

That said... I really feel that providing your own interface to the help system is the best way to go about providing logic to choose which topics are shown.

Can you help me understand how this would work? I just don't see how to do it with the tools now available.

Here's my task: help button X displays a different version of topic A for each user role. Each version of topic A has links to a different subset of topics B through G. Topics B through G all have links that "Return to topic A," which resolve to whichever version of topic A is appropriate for this user's role.

If Advanced Help had a Back button that would solve my immediate problem -- although it's not a general solution, and mere content changes could make it inappropriate.

Meanwhile, I don't see any way to solve the problem without having a separate set of topics Bn through Gn for each role, differing only in the destination of the "Return to" link.

Removing some drama from the title ... Interesting discussion. Fundamentally, advanced help makes some design decisions which make it very portable but limited in features. I don't think we can resolve the two needs fully. It might be that "partitioning" is an answer to role specific help but I'm not yet clear on what Earl means there. Earl - feel free to elaborate since someone might send a patch one day :)

By partitioning I mean that there's only one permission; you either have access to all the help or you have access to none of it.