From p...@designhive.com on October 21, 2012 13:19:23

I'll also be investigating the accessibility of calling the help as part of issue #298 , which has some crossover with this.

From p...@designhive.com on March 27, 2014 02:32:44

The pophelp is now available as flat files ( https://github.com/textpattern/pophelp ) so this gives the future option of including help directly within releases, not relying on the RPC server. It could be changed to XML or something else, if we don't want to rely on Textile to parse it.

From stefdawson on March 27, 2014 03:09:21

Great stuff. We'll have to figure out if it's worth including the files in releases. Part of me thinks it's a good idea -- like we do with the default lang strings in lang/en-gb. Nice fallback, guaranteed to have all help topics available in at least English, and it's relevant to the release, shielded from remote changes that have the propensity to cause confusion when the UI changes between versions.

If we do that, we'd probably need a mechanism for fetching ("installing") non-English help topics, like we do with languages. The simplest option might be to just hijack the Languages panel. So when you click to install / update a new language, you get the DB strings and the help topics too. Plus it gives the option to "install from file" by grabbing a zip file of all the help topic files and unpacking them in a help subfolder.

One thing I'm not sure of is the impact on plugin authors. Currently people can "install" a Textpack easily enough, and they can be bundled with a plugin for auto-install (erm, mostly). But installing plugin-specific help topics for functionality (e.g. prefs) would require writing files to the help folder, and managing the subsequent clean-up on plugin deletion. We could abstract some of that away with API calls, if it's deemed useful. Or we could 'install' the help content in the database txp_lang table like we do with regular strings.

Not quite figured out the best way to approach this yet. Thoughts and ideas welcome.

Current status is that @petecooper is batch converting the English (GB) pophelps at https://github.com/textpattern/pophelp into raw HTML. We will then clean-up the output and integrate this into work on #838.

See also: textpattern/pophelp#32 for completeness.

Please check the work of popHelp, this functionality is already available.

This is fantastic, makss. Thank you. The popup is so much nicer than the separate window, and it works beautifully in other languages too (I gave it a quick test with a fr_pophelp.xml file).

The pref is a great idea too. One thought: in future, are we thinking of offering pophelp in a variety of formats? If so, would it make sense to rename the pref now and (maybe) use a select list here instead of a yes/no radio? Then we could more easily extend the system in 4.8 and beyond. For example:

Help system

• None
• Pophelp
• Slidey drawer thingy
• Menu
• ...

As it stands, if we define those as constants in future, we'll need to ensure that 'pophelp' = '1' so that people who have set the current 'use pophelp' yes/no value retain that setting in the next version. But then other values won't make sense and we get in the same pickle we have now with use_textile taking on three or more values, some of which don't even relate to Textile!

Renaming the pref now to something like help_system offers us one advantage: the current name is a 'boolean' name ('enable' something), whereas a more generic pref name would make it more extensible in future (even if we elect to just store the actual values as numbers).

What do you think?

Hi Stef, for now and foreseeable future the pophelp will be only solution. Not adverse to a slide drawer one day though if satisfactory UI/UX is found (I’ve not found anything I’m 100% happy with though).

That's cool. Just want to make sure that new pref options are as flexible as we can define, so we don't get into the situation we have now, where we end up overloading prefs with options that don't make sense to the pref name itself.

Things that start enable_ or disable_ for example, ring alarm bells in my head because then the prefs can only have two states: on/off forever more, unless we faff with altering everyone's prefs during upgrade if we rename things in future.

EDIT: In this case, even if we keep the options as yes/no now, having the pref named help_system (or something) is neater.

Yes, you are right. We must try to make a flexible option.
As for the name for preference module_pophelp:

• None
• Pophelp
  (if necessary, then add more)

For the future help system, we can use the pref: module_help.
Maybe someday we will have: module_link, module_image, module_file, module_comment, ...

module_pophelp is fine. Is the plan to make pophelp separate from general help then?

I envisaged that we have the inline instruction help always available - and that's for an admin to set up by hand. After that an option for:

• no additional help at all (for people comfortable with the system or those that use inline instruction help extensively).
• OR pophelp on individual widgets via the '?' links.
• OR general help for all widgets on the page in one slide-out panel (although this might be tricky on the Prefs panel because each sub-page of prefs is just switched via JS).
• OR a pulldown help menu with the groups->topics for that panel available.
• OR ...

i.e. one pref to decide on one of the above options. But if the aim is to keep 'pophelp' and 'help' separate then that's also cool.

I would like to make two independent settings, one for pophelp, and the second for help (maybe there will be more settings here). Software is going to be one class, but I would like to share them logically in the interface.

Can probably close this issue now? As and when I spot missing English pophelp items I'll write them and pull into core.

Yes, can close it.

Yay! Well done @makss - lovely stuff! 👏👏👏

Great job, @makss -- thank you!