Update hook_help for Image module

Using https://drupal.org/node/2028799#comment-7894195 as a starting point, the patch:

• updates urls to use the Drupal 8 url replacement
• Changes the field description to match the link field (pointing to field and field_ui documentation).

The copy/paste from the Link module needs to not say "link" in it. :)

Also, you might look at what is being done for the File module. I think the Image module help needs to say more specifics about the Image field settings and formatter settings than what is here?
#2031177: Improve help for file module

The copy/paste from the Link module needs to not say "link" in it. :)

You think? ;)
I'll go over it again tomorrow if no one beats me to it.

Update gives extensive information about the different settings and options for the image field.
I wanted to discuss if this is the right amount of information or too much? (some of the info comes from the description of the form item).

There is also an inconsistency with these form item descriptions, or is there a good reason why:

Enable Alt field
The alt attribute may be used by search engines..

Alt has a capital A in the first line, but not in the second?

Last but not least, this patch assumes that the system module will describe the file system, as discussed here: https://drupal.org/node/2031177#comment-7893741

#6: image-help-text-2091337-6.patch queued for re-testing.

RE #12 - that is just how field settings work in general. All of the settings in the Field Settings tab are also shown on the Edit tab, for fields -- or at least, that is how it has been in Drupal 7. In any case, it is not specific to the Image module. They are the same setting.

Ugh. That is at least a usability bug. Yes, please file an issue and explain just what you did in comment #14 -- that is very very confusing.

I'm postponing this issue until the UI issue is resolved. If you can find that issue, can you link it here as "related"? Also moving this to the image module component since it seems like we need the maintainers to weigh in on what the intended UI behavior is so we can document it in the help.

We just had a change to hook_help, on this issue: #2183113: Update hook_help signature to use route_name instead of path.

Here is the change record: https://drupal.org/node/2250345

This patch will need a reroll for this change.

@jhodgdon - The hook_help was already as per #2183113: Update hook_help signature to use route_name instead of path.

But it was not getting applied in current core code so I have made the required changes in the patch. Please review attached patch.

This issue probably needs to get back to "active" status. Can someone check and see if the UI problem with default images (see comment #12 and #14) has been resolved? Can we write coherent help for this module now?

Instead of having one critical parent issue I have been asked to change the status of each child issue.

I don't think that this issue is critical or major, so leaving it as Normal. But we still need to do this.

Looking at the latest patch it seems to have replaced mentions of the Image module with the File module. That wasn't right... so I think we need to start over with the current Image module hook_help, and review that with the current Image module functionality and go from there.

So... The latest patch here didn't apply any more, and anyway it seems to be changing the Image module help to be File module help. So we definitely do not want that patch. The patch on #11 looks much the same.

So I went back to the starting point of the help currently in the Image module, and sort of applied the patch by hand, keeping some existing sections of help that had been added on other issues. Then I made additional edits to clarify, make more concise, copy edit, and organize the page.

A few notes:

a) I looked into the problem discussed above about default images. That is #1999232: Default image upload on edit and field settings tab is confusing and while I don't think the UI is great, I think that can be pretty easily fixed on the other issue so I don't think we should hold this up.

b) In help you have to be careful about making links to pages that depend on other modules. Image depends on File, which depends on Field, but they don't depend on Field UI. So that link has to be done a bit carefully.

c) I was going to make sure we talked about image toolkits, since that was part of the help at some point for this module. However, I realized that this is part of the System module, so I added a note to #2091363: Update hook_help for System module about this instead.

Anyway... here's a patch!

Thanks for the great review! Here's a new patch. I pretty much adopted what you suggested, hopefully making it even a little clearer and more concise. In the last bit, I don't really even think we need to mention whether/when it can be changed. Thoughts?

Please do! Two people agreeing that the Help page looks good should be enough. ;)

This is so much better. New users might actually be able to make sense of image styles.

I noticed within a section of the definition list paragraph tags are being used within the dt tag causing inconsistent formatting. I'll roll an updated patch with multiple dd tags in place of the p tags. I know p tags can be used within dt tags, this is one reference, http://reference.sitepoint.com/html/dd, but multiple dd tags are also allowed and will keep everything looking the same.

Here is the updated patch.

The spacing changes in #35 look good to me. I've removed a few unnecessary commas.

Let's try this again.

One last try.

I was having end-of-file whitespace issues with those patch attempts because I had some cruft that didn't belong in the patches I was trying to remove by hand, but the interdiff from comment #36 should still be good for the changes between the patch in #35 and the patch in #40.

To be clear, here's an interdiff between the patch in #35 and the patch in #40.

Great! I think several people have now agreed that the text in this help is good, and I like the cosmetic and comma changes since my last patch, so I'll go ahead and mark this RTBC. Thanks everyone!

Whoops, guess we need a rerolle here.

Reroll of #40.

I don't understand enough about the tests for the test logs to make much sense, so I asked about the test failures in IRC and mikeker pointed out that the route image.style_list was recently changed to entity.image_style.collection in commit 3d14a7d25ac370a4616d095ade2f2d87de40b3b2.

This patch attempt is the same as the patch in #46 with image.style_list changed to entity.image_style.collection.

Finally a patch that passes tests :)

Thanks! The reroll and URL route fix look good to me. Back to RTBC.

Here is a paste of the text as it actually appears for simpler review:

About

The Image module allows you to create fields that contain image files and to configure Image styles that can be used to manipulate the display of images. See the Field module help and the Field UI help pages for terminology and general information on entities, fields, and how to create and manage fields. For more information, see the online documentation for the Image module.

Uses

It seems to me that the "Configuring image fields" and "Configuring image field file storage" should be merged - since the user can not do one without the other through the UI. Also "Configuring image fields for accessibility", "Configuring default images for image fields" and "Configuring image field behavior" are to me all subsets of configuring image fields.

and the subdirectory with the public or private file storage - I think this should be subdirectory in the

Thanks, good suggestions!

In other hook_help text, we've separated out the field settings from the display/form display settings (they're on a different page, after all), so I went ahead and left that "Behavior" section as a separate section. But I did retitle it to be more consistent with the other pages, and use the terms formatter and widget as we do in the other help.

I also took out all the headers for the other "configure" sections, so basically we have one header and a bunch of paragraphs (technically DD sections) within it. I added an "also" here and there, nad fixed the "with" to "in" the subdirectory problem.

So, here's a new patch and an interdiff. Can someone please review? Thanks!

I tested the "admin>help>image on simpletest

+ tested all links on page [no problems encountered]

+ added new image style with long title name

+ added new image style with short title name

OK. I'm not sure why you tested those pages on this issue, but fine. So can someone please review the help and mark this RTBC if it's OK, or Needs Work (with a comment) if not? Thanks!

Confirmed Update hook_help for Image module.

Changing to RTBC

Documentation is not frozen in beta. Committed 61eae01 and pushed to 8.0.x. Thanks!