Improve installation instructions

Here's a comment from the code in 6.x-2.x-dev:

* Returns an array of library directories from the all-sites directory
* (i.e. sites/all/libraries/), the profiles directory, and site-specific
* directory (i.e. sites/somesite/libraries/). The returned array will be keyed
* by the library name. Site-specific libraries are prioritized over libraries
* in the default directories. That is, if a library with the same name appears
* in both the site-wide directory and site-specific directory, only the
* site-specific version will be listed.

Using site specific editor versions should be ok.

There has been discussions about this before. The help text on admin/settings/wysiwyg shouldn't to be too long or "bloated" (not the exact word I was looking for but I hope you understand).
The help text doesn't explicitly say that sites/all/libraries is the only directory, but it was chosen as an adequate example.

Can we merge #487910: Tighten and improve help text at admin/settings/wysiwyg into this issue, please? And close the other issue? Thanks.

Doing it myself:

Current text:

Extract the archive and copy its contents into a new folder in the following location:
sites/all/libraries/whizzywig

So the actual library can be found at:
sites/all/libraries/whizzywig/whizzywig.js

Recommended change:

Extract the archive and copy its contents to sites/all/libraries/whizzywig. The actual library must end up at sites/all/libraries/whizzywig/whizzywig.js.

Screenshot for usability team - if they care.

Sure we care, would be more then glad to review contribs.

As I am trying to discover the reasoning behind these sentences, I would try to avoid making a sentence which says or, as that doesn't describe its use unless you understand siteName

IMHO, Drupal users already know the concept between sites/all/modules and sites/example.com/modules. The very same logic applies here, so I'm really not sure whether we have to explain it again. Likewise, users already know that they can put their theme into sites/all/themes or sites/example.com/themes. In the end, I expect this to be used only by advanced users anyway -- after all, who really builds multi-sites with Drupal and does not know these basics?

Of course, we could mention that it works the same way.

Regarding repetition: Yes, at least the second path is specific to each editor library. Before the current release of Wysiwyg API, we only displayed the first path. However, users still struggled with installing the libraries correctly.

Because if you downloaded an editor that extracts itself into a folder

tinymce_3_2_1_1

then you do not directly know whether you should rename it, so it's:

sites/all/libraries/tinymce

or whether you should create that 'tinymce' folder and put the extracted folder in there:

sites/all/libraries/tinymce/tinymce_3_2_1_1

The problem gets bigger, because some editor libraries are not packaged into a self-containing folder. Others are, but the self-containing folder uses a completely different name, such as latest.

However, there are some libraries that come nicely packaged - and can just be extracted into sites/all/libraries. So the entire issue applies only to some libraries.

That is currently explained in the handbook: http://drupal.org/node/371459

By amending the second path, we tried to clarify the actual position in the filesystem. Users need to know the expected library location in the first place for "easy" libraries. For some libraries, users also need to have a clue about where a specific file in the library is supposed to be located, so they can extract and locate the entire library accordingly.

To improve the install process, I would opt to only show the installation text of the chosen editor and hiding the other. Really not being an advocate of the good old collapsible fieldset: here it might be a good workhorse. Given some typography and highligting, this looks by far less cluttered:

I don't really see a way to shorten the help text, as this is a multi-step process:
1. create new folder with name of editor in /sites/all/libraries
2. extract archive
3. copy contents of archive into the folder

writing this in an ordered list probably does not help, this would have to be user-tested. But given you show only the description for the active editor, it could be more detailed as you only see it once. As Comments on the doc page show, people don't get it, and a nice description with maybe even a small graphic would not be overkill but improve adoption. Though the problem sun describes in #11 is a nasty one that gets worse the more editors Wysiwyg supports. So how about a futuristic, but

Consequent solution

Given the fact that Plugin manager makes it into core for Drupal 7:
Automatize the install process.
I am not sure which cans of worms this opens (keeping track of location of stable versions of all editors, trusting a third party source and a handful more).

But from the eyes of the user (especially a non-techy one, which is exactly the audience for a wysiwyg), this is by far the best IMHO. If you want to let the user choose the Editor version, plugin manager could open up a small Iframe of the project page of the respective editor.

a) How comes you have HtmlBox in that screenshot? I only have that on my local development box?! :P

b) Plugin Manager is out of scope for now. If there'd be a task force trying to integrate Wysiwyg module with it, I'd support that though.

c) I'm not really sure whether collapsed fieldsets wouldn't increase the WTF-factor - because new users will have to recognize that very small arrow visually first. I implemented collapsible contents exactly like that in Upgrade Status module - and looking at it today I find it pretty hard to recognize, but also to point and click those arrows.

d) An ordered list would make sense, IMHO.

for c): Well, if you use collapsible fieldsets or vertical tabs or maybe even the concept of Views 2 to to have all settings on top and show seperate pages at the bottom - it would improve readability and scannability to hide all instructions than the selected one I think.

For the instructions: How about this solution? Hopefully near to foolproof... :)

This would mean you have to keep track of all the editors and the file structure when you expand the zip files, and change the graphic and description when that changes.
I guess this won't happen very often and way well be worth the effort.

For the everyday user that just does not matter. He wants to know where to put them and done. Putting them where you like I'd see as an instruction for advanced users that could be somewhere in the Docs, but would not need to be in the instructions. I think this would only confuse people.

BTW:

"The following list contains a list of currently supported editors"

list contains a list?

FCKeditor readme instructs to use sites/all/modules/fckeditor/fckeditor for the second part of the install, making it clear that this is NOT sites/all/libraries/fckeditor/fckeditor.

That install method works in my 6.14 and 6.15 setup.

However, the Administer > Site Configuration > Wysiwig page states that FCKeditor is not installed.
And when I create a path for sites/all/libraries and move FCKeditor there, FCKeditor no longer appears on the Modules page, and the Wysiwig page reports voluminous errors at the top of the page.

Now, I am reasonably satisfied with the funcionality I get from FCKeditor, but I am concerned that my install is not totally correct since Wysiwig (at least on its page where it lists most of the potential editors for it) reports it is not installed.

Is this how it appears on all 6.14 - .15 installations?

Is this just a meaningless anomaly?

What should I do?

If FCKeditor appears on the Modules page, you are also using fckeditor.module which is a completely different implementation of the FCKeditor editor library for Drupal. You can only use either Wysiwyg.module or Fckeditor.module, as they both try to do the same thing!

The other module only deals with the FCKeditor llibrary, while Wysiwyg module aims to work with multiple editor libraries at once. If you're using fckeditor.module, you should place the editor library in /sites/all/modules>/fkceditor/fckeditor as that's where that module expects it to be. If you're using Wysiwyg.module, you should place the editor library in /sites/all/libraries/fckeditor (along with any other editor library you also wish to use).

As stated on Fckeditor.module's project page, these two modules take different approaches to how/where the editor appears and is configured. Wysiwyg.module is closely tied to and configured along with input formats while Fckeditor.module can be configured on a per field basis. There are some other differences as well, like which settings can be configured via the GUI etc, but I encourage you to try both modules, one at a time, and then decide.

As an aside, I just tried to install WYSIWYG.module v2.1 and the newest CKeditor library on a d6.x site today, and if the CKeditor folder is installed at sites/example.com/libraries/ckeditor/, the admin/settings/wysiwyg configuration page refuses to report that the CKeditor library is installed.

If, however, the ckeditor/ directory is placed in sites/all/libraries/ckeditor/, the administration screen instantly reports that CKeditor is correctly installed. Remove or rename the sites/all/libraries/ckeditor/ directory and the WYSIWYG module goes back to reporting that there is no editor installed, even if there's still an identical copy at sites/example.com/libraries/ckeditor/.

I think that the code's logic should be verified before the documentation is finalized and pushed out there, as the module may not currently do what Drupalistas expect it would. :)

This might help too: #542940: [meta] Support for downloading libraries via Composer

removing review

Would be great to at least have the version numbers listed of working libraries seeing as the latest TinyMCE doesn't work.

Also EpicEditor changed URLs - http://oscargodson.github.io/EpicEditor/docs/downloads/EpicEditor-v0.1.1...

And the YUI editor (Download) link goes directly to download the library (which is different than all of the other links).

Bringing some of these improvements into the next stable release would be great.

@mgifford, yeah, I've wanted to list the 'last officially tested' version number for some time, haven't gotten around to compile that list and add it in there. Should be as simple as adding a new key to the editor meta data with the version number, add a column with those numbers to the install instructions and also highlight any profiles using an editor library with a version number above the one in the column.

There's a couple of open issues for EpicEditor, that is one of them. Hadn't noticed about YUI, thanks for that.

Hard to keep track of all of these moving parts. But fortunately your in a community and don't have to handle all of the responsibility.

Please continue in #2375679: Improve profile management.
That issue has a patch which implements ideas from here and this issue started off as a semi-related support request anyway.
For reference, supported editor version information is also at https://www.drupal.org/node/596966.