From editor_help():

      // @todo: Mention the availability of the built-in core WYSIWYG (CKEditor)
      // when it becomes available. See http://drupal.org/node/1878344.

#1878344: Add CKEditor JS library to core and more importantly #1890502: WYSIWYG: Add CKEditor module to core are now in core, so the help text should reflect that.

Files: 
CommentFileSizeAuthor
#18 text-editor-help-text-2033471-17.patch5.68 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,101 pass(es).
[ View ]
#18 interdiff-2033471-16-17.txt2.69 KBifrik
#17 text-editor-help-text-2033471-16.patch5.78 KBWim Leers
PASSED: [[SimpleTest]]: [MySQL] 58,071 pass(es).
[ View ]
#17 interdiff.txt4.91 KBWim Leers
#15 text-editor-help-text-2033471-15.patch5.95 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 58,111 pass(es).
[ View ]
#8 2033471-8.patch6.42 KBPancho
PASSED: [[SimpleTest]]: [MySQL] 56,534 pass(es).
[ View ]
#6 2033471-6.patch3.45 KBPancho
PASSED: [[SimpleTest]]: [MySQL] 56,974 pass(es).
[ View ]
#1 2033471-1.patch2.66 KBWim Leers
PASSED: [[SimpleTest]]: [MySQL] 56,782 pass(es).
[ View ]

Comments

Wim Leers’s picture

Assigned:Unassigned» Wim Leers
Status:Active» Needs review
StatusFileSize
new2.66 KB
PASSED: [[SimpleTest]]: [MySQL] 56,782 pass(es).
[ View ]

Thanks for reminding us! :)

How about this? I'm not too fond of the wording, but can't think of anything better atm. Suggestions?

Pancho’s picture

'The Text Editor module does not provide any text editor libraries itself. The CKEditor module is part of Drupal and provides the CKEditor text editor.

"part of Drupal core"?

Most installations of Drupal include a module that provides a text editor library

Sounds slightly weird, and why would we make assumptions on this?

which may be enabled on the <a href="@modules">Modules page</a>.

"Installed", as of #1199946: Disabled modules are broken beyond repair so the "disable" functionality needs to be removed... :)

Additional modules that provide text editor libraries may be <a href="@download">downloaded from Drupal.org</a>.', array('@modules' => url('admin/modules'), '@download' => 'http://drupal.org/search/site/wysiwyg%20module')) . '</dd>';

OK, but how about this:

'The Text Editor module does not provide a specific text editor library itself. Rather, it gives you the choice to install your favorite text editor module on the <a href="@modules">Modules page</a>. While the CKEditor text editor module is already bundled with Drupal core, you will find Drupal modules of many widely used text editors on the <a href="@download">Drupal.org website</a>.
Wim Leers’s picture

"part of Drupal core"?

I thought we never referred to Drupal core as "Drupal core" in UI strings? I could be wrong of course.

RE: your suggested text: MUCH, MUCH better — thanks! :)

RE: the d.o link, maybe refer to https://drupal.org/project/modules?f[0]=im_vid_3%3A63 instead? I very much dislike how that URL looks though — it seems it could change at any point in time. We could ask the d.o webmasters to create an alias for us though, but I'm not sure if that's a common practice. I guess we should go with a regular d.o link for now.

Care to roll a patch with your suggestions? :) I'll RTBC!

ifrik’s picture

There was already a ticket for this: #2031743: Improve hook_help for text editor module - but I suppose that got over looked because the module is actually called "editor" but refered to as "text editor" on the Extend (Modules) and Help pages.

I've just made a patch with more extensive rewording and additional Uses.
So maybe the best way to avoid any further double work is if I look at the patch in and the proposal for wording here, and see what can be included in my patch?

I'll also change the list on #1908570: [meta] Update or create hook_help() texts for D8 core modules.

Wim Leers’s picture

#4: sounds good!

Pancho’s picture

StatusFileSize
new3.45 KB
PASSED: [[SimpleTest]]: [MySQL] 56,974 pass(es).
[ View ]

So should we close this one as duplicate or move it forward anyway?
I'm adding the patch requested in #3, so you can decide.
Actually I like it better than the current proposal in #2031743: Improve hook_help for text editor module, plus it immediately solves a @todo, so I personally think we should commit this first and then take our time reworking the whole help text on that basis.

Re:

I thought we never referred to Drupal core as "Drupal core" in UI strings? I could be wrong of course.

I searched the Styleguide but couldn't find. However, we need to clarify what CKEditor is bundled with. It's not the installs, it's not the Drupal project, it's Drupal core.

Wim Leers’s picture

Status:Needs review» Needs work
+++ b/core/modules/editor/editor.moduleundefined
@@ -20,14 +20,12 @@ function editor_help($path, $arg) {
+      $output .= '<dd>' . t('The Text Editor module does not provide a specific text editor library itself. Rather, it gives you the choice to install your favorite text editor module on the <a href="@modules">Modules</a> page. While the CKEditor text editor module comes already bundled with Drupal core, you will find Drupal modules of several widely used text editors on the <a href="@download">Drupal.org website</a>.', array('@modules' => url('admin/modules'), '@download' => 'http://drupal.org/search/site/wysiwyg%20module')) . '</dd>';

The last URL refers to the WYSIWYG module specifically. That should not be the case. (I know it was the original text too, but that should not have been the case.)

Further, "The Text Editor module does not…" and "… your favorite text editor module …" may appear to be the same thing to the end user. Especially in languages like German, where nouns are uppercased. Can you word that part differently?

Other than that, this looks good to me :)

Pancho’s picture

Status:Needs work» Needs review
StatusFileSize
new6.42 KB
PASSED: [[SimpleTest]]: [MySQL] 56,534 pass(es).
[ View ]

Thanks for your review!

1.
Best match for the URL would probably be Modules: Filters/Editors / 8.x
This should really be improved on the d.o website until D8 release.
I'm going to open separate issues for that (one in the Drupal core project being postponed on another one in Drupal.org), so we can go with it without yet another @todo.

2.
And yes, you're right with the other issue, too. Capitalization or not - confusion is very hard to avoid.
I looked around and thought about it a lot. We can't say "WYSIWYG editors", because there are non-WYSIWYG-editors. We can't say "HTML editors" because their output could be another markup which is just later filtered to HTML. "text markup libraries" would work but not without the "libraries" part.

However, it should be okay to speak of "Rich-text editors" which is well established and pretty much understandable, and which covers quite all use cases. With "Markup editor" there would have been another good alternative, but the other one seems better.
Rich text is pretty much everything that has any kind of markup. This here is rich text, and BUEditor - which we're using here in the queue - is yet another Rich-text editor. It's not WYSIWYG, but it aids us in producing rich text.

The only case of a Text editor implementation that wouldn't be a rich-text editor is the case of a toolbar with buttons that strictly don't add any markup, but only add unformatted text blocks. In theory, this is imaginable, but certainly won't be the 80% use case, not even a 5% usecase. Not sure about the remaining 5%.

So I decided to use just "rich-text editor" in all of the help text. I also replaced "WYSIWYGs and/or toolbars" by "rich-text editors", because the dichotomy doesn't work well: there is a gradual transition between a full WYSIWYG and a mere toolbar, and we don't want to unnecessarily deepen a wrong dichotomy, especially not if it unnecessarily makes things more complex to understand.

3.
However, no matter how we describe it, it remains slightly confusing, unless we rename the whole module to "Text Editor API" or or "Text Editor Canvas" or "Rich-text area" or something. It might be worth another thought, because once we release, the name is in the world, and we can only answer the support requests.

In any case it would be awesome if UI name and system name of the Text Editor module could be assimilated. I know this would lead to renaming classes and everything, but a consistent UX is so important in the long-term that a one-time conversion should be worth it.

But both aspects certainly need to be soundly weighed, and are certainly out of scope here.

4.
Links that should exactly match the page title of a specific path, shouldn't be translated with the complete string, but should go with the translation of the actual page title. Same would hold for other kinds of labels.
I replaced two occurences, only left the Filter module help page with its inexpressive page title.

So take a look at the patch and see if there's something you don't like.

ifrik’s picture

Looks like we now ended up with double work :(
#2031743: Improve hook_help for text editor module

Wim Leers’s picture

Assigned:Wim Leers» Unassigned
Status:Needs review» Needs work

#8:
1. Good :)
2. No, please use "Text editor". That's what the module is called, and what all existing UI strings use. If you want to call it something else ("rich-text editor" or anything else), then that should be done and discussed in a follow-up issue.
3. Correlated to point 2, as you already say. Should be part in the same follow-up issue as point 2.
4. Ok.

+++ b/core/modules/editor/editor.moduleundefined
@@ -17,17 +17,15 @@ function editor_help($path, $arg) {
+      $output .= '<p>' . t('The Text Editor module provides a framework to extend the user interface on text fields that allow HTML input. Without Text Editor module, fields accept only text where formatting must be typed manually, such as entering a <code>&lt;strong&gt;< / code> tag to make text bold or an <code>&lt;em&gt;< / code> tag to italicize text. The Text Editor module allows these fields to be enhanced with rich-text editors, which make entering and formatting content easier. For more information, see the online handbook entry for the <a href="@doc_url">Text Editor module</a>.', array('@doc_url' => 'http://drupal.org/documentation/modules/editor/')) . '</p>';

"strong to bold text" and "em to italicize text" are technically incorrect; it is CSS that determines whether they are bolded/italicized, not the HTML tag. I'd use the example of "blockquote to denote a quoted piece of text" or something else that is less contentious.

+++ b/core/modules/editor/editor.moduleundefined
@@ -17,17 +17,15 @@ function editor_help($path, $arg) {
+      $output .= '<dd>' . t('The Text Editor module does not have its own configuration page. Instead it enhances existing configuration pages with additional options. Rich-text editors are attached to individual text formats, which can be configured on the @formats_link page</a>. Each text format may be associated with a single rich-text editor. When entering content with that text format, the associated rich-text editor will automatically be enabled.', array('@formats_link' => l('Text formats and editors', 'admin/config/content/formats'))) . '</dd>';

"with that text format" -> "in/using that text format"?
(Not sure, I'm not a native speaker.)

Other than that, I think this is good to go. Almost there! Thanks :)


#9: well, to be fair, that's not Pancho's or my fault. This issue was the first to have a patch, and it is the only one that is discoverable (component maintainers cannot be expected to check the "Documentation" component). Pancho made suggestions in #6, to which you did not reply, and only several days later you posted an updated patch in the other issue.

Pancho’s picture

Thanks for your review!
Some remarks, though:

2.)
You might have possibly misinterpreted this. Of course I'm still using "Text Editor module" as its current name.
What I'm calling "rich-text editors" is the specific libraries that may be provided by implementing modules.

This still seems to be a preferable solution to avoid talking about three different things sharing a name so similar it's hard to keep apart.
We don't really want a "Text Editor module" dealing with "text editor modules" implementing "text editor libraries".
It's much more comprehensible to say "Text Editor module" deals with "rich-text editors" available as Drupal modules.

3.)
As said before, this is out of scope, but also isn't really connected to 2.
The essence of this proposal is not about "Text Editor" resp "Richt-text Editor" but about adding something like "API", "area", "canvas" or maybe "framework", setting it a bit apart from its actual implementations

Wim Leers’s picture

#11:

2. I haven't misinterpreted :) I want consistency. Calling the module "Text Editor" and then referring to text editors as "rich-text editors" is inconsistent. I don't see anything wrong with this:

We don't really want a "Text Editor module" dealing with "text editor modules" implementing "text editor libraries".

Again, it's fine to advocate for a different naming scheme, but this is not the appropriate time or place to do it.

3. Aha, I see your point. The "area" and "canvas" suffixes are highly confusing, but the "API" suffix is not. I'm fine with renaming the module in the .info.yml file to "Text Editor API", and that does not require renaming files or classes. Just changing the human-facing strings would be sufficient.

ifrik’s picture

With the renaming in the info.yml file the patch doesn't seem to work anymore.
1) The agreed link text to the online documentation is "online documentation for the Text Editor module"
2) The Modules page has been renamed as Extend.
3) Once the text editor module is enabled, the Formats page is called "Text formats and editors" page.
3) I don't think that it makes sense to talk about "rich text editors" instead of simply "text editors". Not only because it is the name of the module, but because not all text editors that can use this frame work might be rich text editors, or at least might be identified as such (see for example TinyMCE). Using a different term therefore does not add any clarification for the reader.
4) Using a text editor of your choice: "your favorite editor" is not really useful either because the preferences of the site builder don't always match those of the users :-) And I don't think that we give links to search queries on drupal.org as reference in the documentation. What is important however is that in addition the the Text Editor module you need another module - and that can either be core or contrib.

Taking into account what should be covered by the help pages for the individual text editors, and comments made on the duplicate issue as well as here, I would propose the following. Do you want me to make a patch for it with all the links in place?

About
The Text Editor module provides a framework that other modules (such as CKEditor module) can use to provide toolbars and other functionality that allow users to format text more easily than typing HTML tags directly. For more information, see the online documentation for the Text Editor module.

Uses
Installing text editors
The Text Editor module provides a framework for managing editors. To use it, you also need to enable a text editor. This can either be the core CKEditor module, which can be enabled at the Extend page, or a contributed module for any other text editor.
When installing a contributed editor module, be sure to check the installation instructions, because you will most likely need to download and install an external library as well as the Drupal module.

Enabling a text editor for a text format
On the Text formats and editors page you can see which text editor is attached to each text format. You can change this by clicking on the configure link, and then choosing an editor or none from the Text editor drop-down list.
The text editor will then be displayed with any text field for which this text format is chosen.

Configuring a text editor
Once a text editor is attached to a text format, you can configure it by clicking on the Configure link for this format. Depending on the specific text editor, you can configure it for example by adding buttons to its toolbar. The buttons are typically for functions like inserting links, making bullet lists, and other formatting tasks, and they typically insert HTML tags into the field's source. It is important to match the buttons to the text format. For instance, if a text format filters out link tags, do not include a link button in the editor configuration for that format. For more details, see the specific help page of that editor and the Filters help page.

Using different text editors and formats
If you switch the text format on a field, the editor will change as well because the text editor configuration is attached to the individual text format. This allows the use of the same text editor with different options for different text formats, as well as allowing users to choose a text format with one out several text editors.

Wim Leers’s picture

#13 is not clear to me. Which parts were addressed to me? Please use code tags or a horizontal rule to separate different parts.

ifrik’s picture

StatusFileSize
new5.95 KB
PASSED: [[SimpleTest]]: [MySQL] 58,111 pass(es).
[ View ]

The patch in #8 doesn't seem to work anymore due to some changes in the info.yml file.
The help text in this issue takes the proposed wording and comments in this issue as well as in #2031743: Improve hook_help for text editor module into account.
The link to the ckeditor help page currently breaks because the help page is still missing #2029737: Create hook_help() for ckeditor module

ifrik’s picture

Status:Needs work» Needs review
Wim Leers’s picture

StatusFileSize
new4.91 KB
new5.78 KB
PASSED: [[SimpleTest]]: [MySQL] 58,071 pass(es).
[ View ]

I fixed a lot of small inconsistencies, fixed a few significant errors

The biggest error was this statement:

It is important to match the buttons to the text format. For instance, if a text format filters out link tags, do not include a link button in the editor configuration for that format.

That is utterly wrong. The user doesn't have to worry about this anymore. We spent an insane amount of effort to make this as simple as possible in #1894644: Unidirectional editor configuration -> filter settings syncing.


I had first written a dreditor review, but then dreditor lost all my comments. It was faster to just reroll the patch with the fixes.

ifrik’s picture

StatusFileSize
new2.69 KB
new5.68 KB
PASSED: [[SimpleTest]]: [MySQL] 58,101 pass(es).
[ View ]

Looks good.
I've shortened the section on "Configuring" even more to make it more generic and instead mentioned the other help pages again.
Also fixed a missing space in the last line.

Wim Leers’s picture

Status:Needs review» Reviewed & tested by the community

Great, thanks :)

Wim Leers’s picture

Issue tags:+quickfix, +sprint, +Spark, +CKEditor in core

.

webchick’s picture

Status:Reviewed & tested by the community» Fixed

Awesome stuff, folks!

Committed and pushed to 8.x. Thanks!

Wim Leers’s picture

Issue tags:-sprint

.

Automatically closed -- issue fixed for 2 weeks with no activity.