The help page should be checked, and a link to the ckeditor as a core module included.

#5 text-editor-help-text-2031743-4.patch6.23 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 57,039 pass(es).
[ View ]
#1 text-editor-help-text-2031743-1.patch5.81 KBifrik
PASSED: [[SimpleTest]]: [MySQL] 56,521 pass(es).
[ View ]


ifrik’s picture

Assigned:Unassigned» ifrik
Status:Active» Needs review
new5.81 KB
PASSED: [[SimpleTest]]: [MySQL] 56,521 pass(es).
[ View ]

I've added the Ckeditor as a core module, and tried to make some of the broader issues of how to handle text editors clearer.
I couldn't actually try out the installation of additional text editors because I couldn't find a contribe module for D8, so if anything changes with regard to libraries then the help text will need to be ammended in future.

jhodgdon’s picture

Status:Needs review» Needs work

There are a couple of grammar/formatting issues:

a) Refer to "Text Editor" module -- it's not always capitalized correctly.

b) "can use to provide toolbars and other functionalities "... should be functionality.

c) I don't agree that it is a good idea in Uses to talk about "enabling CKEditor" explicitly. Let's go back to how that was before. I think the change in About to say "such as CKEditor" make sense, but not this change in Uses. It can say "such as CKEditor" as well, but don't change it to imply that CKEditor is anything special.

I didn't read through the rest, sorry, a bit short of time today...

ifrik’s picture

But Ckeditor is special in so far as it is in core and doesn't require installing any libraries or contribe modules. Wouldn't that merit it being treated differently?

jhodgdon’s picture

Sure CKEditor is special. But that doesn't mean that the Text Editor module help should tell how to use the CKEditor module, or concentrate on it. The Text Editor module help should say that it lets you configure "text editors such as the CKEditor" (or something like that), and it should tell you how to associate "an editor" with a text format, but it shouldn't tell you how to associate the CKEditor with a text format or how to install the CKEditor module. The help needs to be written more generically.

So for instance I think what the About section does is fine: it uses CKEditor as an example, but makes it clear that CKEditor is not the only available editor.

But the Uses section is way too centered on the CKEditor specifically.

I think the topics in Uses should probably be:
- Installing a text editor (say that these are separate core or contributed modules, and you have to install/enable the module to make it available).
- Enabling a text editor (say that each text format can have one and only one editor associated with it, and explain how to make this happen. I would also leave out the part that says that the Text Editor module has no configuration screen itself. It's not really useful to say what a module doesn't do. Better to explain what it does and how to use it. Referring to the Filter module help as is done now is a good idea.)
- Configuring a text editor (say that most editors have options such as which buttons are visible, and the options can be set for each text format, and explain how to do this)
- Editing with a text editor (say that when you edit a field that accepts formatting, and choose a text format that has an editor defined, you'll see the editor, and when you switch formats the editor will change)

Does that make sense?

ifrik’s picture

Status:Needs work» Needs review
new6.23 KB
PASSED: [[SimpleTest]]: [MySQL] 57,039 pass(es).
[ View ]

I've reworded this with the suggestions from #4.
I'm not quiet happy yet with the bit about the filters so I would be happy about suggestions. My aim was to make the user aware that there can be conflicts or that one might set a button for a format that then gets stripped out again if the HTML tag is not allowed in the filter.
I tried the filters as a seperate definition but that didn't really work either.

jhodgdon’s picture

Status:Needs review» Needs work

It's looking better! I think it can still be improved:

a) Bullet point on Installing:
- contribe module ==> contributed module
- Ckeditor module which can be enabled ==> needs comma before "which"
- The first sentence seems a bit awkward to me... It says:

The Text Editor module only provides the underlying framework and therefore needs to be extended with an additional module.

How about something like this?
The Text Editor module provides a framework for managing editors. To use it, you will also need to enable a text editor module.

- The last sentence ... it only pertains to contrib modules and it means you probably need to download an external library, but I didn't think this was clear. Can we change it to something like:
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.

b) Bullet point on Enabling:
- The first sentence is a bit awkward. Maybe:

On the <a href="@formats">Text formats and editors</a> page, you can see which text editor is attached to each text format.

- Remove the comma after "this" in the second sentence.
- Second sentence: "pull-down module" (end of sentence) should be "drop-down list".

c) Configuring bullet point:
- 2nd sentence: Depending an ==> Depending on
- 2nd sentence: "you can for example add or remove buttons for easier formatting to its toolbar" ==> "you can, for example, add or remove buttons from its toolbar"
- This section needs a rewrite:

Typically a text editor will include buttons to formate characters and paragraphs, insert images and links, to copy and paste content, and to toggle between formated text and the HTML source. A text format is configured by filters which, for example, determine which HTML tags are allowed or whether the use of images is restricted. These filters can impact on the use of the options of a text editor.

I see what you are trying to get at, but I don't think the point has been made... How about this:
The buttons in text editors 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.

d) Using bullet point:
- Last sentence - I think the point here belongs with the Toggling bullet point and not here, and besides it does not apply to all editors (such as BUEditor, the one you see here on for comment editing).
- Maybe we should add a sentence saying that if you switch the text format on a field, the editor will change?

e) Toggling bullet point:
- The bullet point title has a typo: "formated" => "formatted"
- Should this even be here? Is the button (and isn't it typically a link??) for toggling between visual editor and source provided by the individual editor module or by the Text Editor module? If it's provided by the individual editor and not the Text Editor module, let's take this whole bullet point out and put it on the CKEditor help instead. If it's provided by the Text Editor module, then I suggest the following wording for this bullet point:

For each text format, you can choose whether to allow or disallow toggling the editor between visual and HTML source mode. This can be useful for advanced users, because a visual HTML editor normally would transform any HTML tags entered in the editor into plain text. If the option is provided to turn off the visual editor, advanced users can enter HTML markup directly, and then toggle the editor back on to see the result.

(if it's specific to the editor, then maybe this wording can be put into the CKEditor help?)
Wim Leers’s picture

Status:Needs work» Closed (duplicate)

More frequent patch rerolls have been happening at #2033471: Mention core WYSIWYG / CKEditor in editor_help(), plus the first patch was there.