Allow adding help to existing modules

Here's a patch. Approach:

* Introduce option to export help for an existing module.
* For generated code, introduce dependency on a new module, helpinjector, attached. This addresses the potential for conflicts with existing hook implementations when merging into an existing module. Also simplifies generated code.
If an existing module is used, module and info additions are generated as .additions files with a README explaining how to integrate them into an existing module. in both cases, hook_helpinjector() implementations are put into an include file.
* Pull calls to module and help generation into a wrapper function. This will facilitate calling from Drush.

Update phpdocs.

Changing handling of directory selection.

Previously the directory the module was written to was within the files directory. This created permissions challenges when calling help creation from drush because the drush user often won't have write access to the files directory.

If no write access to the files directory, try the temp directory (which the drush user is more likely to have sufficient access to).

Needs careful review, particularly because of the dangerous call to file_scan_directory() with an unlink callback. Somewhere in my testing I ended up with a completely deleted drupal site (all files removed).

I've posted helpinjector as a new module because I'm going to need it as a dependency soon for several Debut features.

Instructions for using this patch.

• Download advanced help and helpinject.
• Apply patch.
• Enable helpinject and book.
• Create and inject help as usual--create book pages with help, use the helpinject icons to attach the help to form elements or to pages.
• At admin/build/helpinject, you will have the option to either add the help to an existing module or create a new module.
• To add help to an existing module:
  • Select the module to add to.
  • Open the files that were generated. Follow the instructions in the helpinject.readme.txt file for copying over text from the .module and .info files into the module's existing files and moving the help and include files.
  • Add helpinjector to the site and enable. Turn off helpinject to confirm the injected help is working.
• To generate a new module (this functionality is not changed by the patch):
  • Don't select an existing module and instead fill out the information for the new module (human and machine readable names).
  • Move the module that was generated and also the helpinjector module to a new site and enable.

Tagging.

I tried to avoid doing a major rewrite, really I did, and the changes here aren't as extensive as they look.

Further work to facilitate #428624: Drush support, including adding help to an existing module.

Significant barrier there was permissions. When running drush, directories created in the files directory were not writable since they were written by the web process.

To address this, moving help generation to two steps.

* First, generate an array of $files containing file names, the directories they are to be written into, and either contents or the source file to be copied from (in the case of file attachments).
* Then actually create/copy the files.

This will make it easy for Drush to call the first step then do its own file writing. Cleaner.

Also includes a fix to #908216: Help injection exported for all books when one book is exported.

Fix typo in code comment.

#428624: Drush support, including adding help to an existing module, which requires this patch, is now ready for review/testing.

Thanks for looking at the patch.

I see the point and I did at first try to write this patch so that it didn't require helpinjector for standalone help modules. I found that doing so added very significantly to the complexity of the helpinject code--we had to implement two completely distinct code generation approaches. Not impossible, but messy.

Now that I've worked more with the code, even without this patch I might be tempted to pull the fairly opaque generated code into a helper module. With this patch, advantages include:

* Parallel code between standalone and integrated modules.
* Keeps generated code simple, i.e., straightforward hook implementations.
* UI is uniform between standalone and integrated updatable. Any change in helpinjector will be available to all help injecting modules.

Soon after writing this I began to think I'd taken a poor approach.

Currently helpinject combines two distinct functionalities: (1) help authoring, (2) injecting help links onto pages, forms, etc. The two currently are highly integrated, in that the injecting is not done directly on generated help files but rather on the nodes that are used for help authoring.

My attempt to enhance didn't go deeply enough. What's probably needed instead is a full refactoring.

Steps would be:

1. Rewrite the help authoring to remove the use of nodes. While handy, the reliance on nodes creates many issues and difficulties:

* Lack of export support, so that it's practically impossible to provide patches on existing help that's stored in helpinject.
* Rendering problems, e.g., node-specific theme HTML injected into exported help.

Instead, the help authoring system should have as its native export format the actual advanced help files. Local storage could be either (a) help files located in the files directory, or (b) a simple database-based entity.

2. Rewrite the injecting to inject native advanced help files, rather than a help authoring format, thus removing the dependency on the help authoring component.