Add filter_tips_short() where appropriate

This does not seem to be right, since help texts are printed by all modules with small letters as the intention of help texts on pages is to provide information on what is available on that page... I would suggest integrating compoe_tips.module into filter.module instead, and use the _help() hook to get the filtered text like it is done for the descriptions and complete helps: not to let the default help mechanism pick up the help text, but collect the items in folder.module instead.

Sounds right to me. One less module to maintain, and an excellent example of the power of the help hook.

Moshe, what opinion do you favor? The one expressed by Dries, or mine? It is not clear to me, since both use the _help() hook in one way or the other.

I have a slightly different vision than either of those posted here.

I'd like for all the modules which currently implement the compose_tips hook (i.e. image.modulle filter, title filter, etc.) to instead use the help hook. They should be able to use (node/add || node/edit) or some similar mechanism in order to signify that their text should appear on node forms only.

If we just left at that, then these texts would be intermingled with other help text for the same page, such as submission guidelines (which should be moved to _help() hook as well). So I propose a 'type' indicator to be returned in the _help() hook just like drupal_set_message(). With type information, the theme can choose to display 'submission guidelines' differently from compose_tips.

I don't think we need a compose_tips standalone page. Brief help texts should be added to the node form page itself and further detail for any item can be provided at an url served by the module.

I also don't think filter.module should be involved in displaying help information like compose_tips.

Well, if we can differentiate between 'submission guildeline' type of help, 'compose tips' type of help or just 'simply help' :) then we can display the compose tips guidelines differently then other help text. In any case, the long tips (like the whole explanation of bbcode) will not fit on the node submit page, so a standalone compose-tips page is needed.

Sine it would only be around a very few new rows added to filter.module, I don't see why it would be a problem to add this to filter.module:

• register 'compose-tips' or 'filter-tips' URL with a menu call
• add a handler function, which simply calls all _help() hooks with
  #compose-tips or #filter-tips as a parameter

Since there are core modules implementing filters, and those filters need more explanation for users, I strongly beleive that the compose-tips feature belongs to core. How would someone adding a comment on a blog about mathematics know that the less then sign or the greater then sign should be written with (X)HTML escaping? He might not know anything about (X)HTML at all. He needs some explanation. He can get that explanation from the compose-tips page.

Note: this post will look better on the web than in email.

"In any case, the long tips (like the whole explanation of bbcode) will not fit on the node submit page, so a standalone compose-tips page is needed."

No. The large page explaining bbcode can be served by bbcode.module. For example, at q=bbcode/help. The bbcode form need only include a link to this page.

Even though it is just a few lines in filter.module, I believe they are redundant. The help system can manage this on its own.

For example:

My proposal involved only core modules also. I agree that no contrib module should be involved in delivering this information to authors.

So if I understand correctly, you would like to see a list of short compose tips somewhere on the node submission page, which all will link to their respective detailed explanation page?

• This makes sense in case you would only like to get information on one particular filter. If I would like to get information on how not to screw up a post with some sequence that a module might parse (ie. how to escape, what to escape), I need to click on all the compose tip links individually, and read all the pages myself.
• Also what a user submitting some text would like to know is not what bbcode does, but how she can write bold text, or how she can add a link. She might read the bbcode help text, and assume she can link to internal website pages with bbcode, while an enabled title module would provide a better tool for linking to internal pages, or an enabled weblink module would provide a better tool for linking to external pages.

I beleive that an overview page would be more desirable then individual explanation pages because of the above two points.

+1 for moshe's suggestion, ie. short filter-tips served by the "type"d help hook linking to longer explanations either on the web or "module/help".

contrary to moshe, i think that *all* enabled filters, incl. contrib modules, should be shortly explained there. we might need a "weight" parameter for the list of filter-tips (first node/html filter, then wiki-style, then contrib modules ...).

i submitted a patch yesterday that implemented a "node_filter_tips" in form_allowed_tags_text() (which is the wrong place). it explains the enabled node/html filters in 3 lines, and still is comprehensive (i think):

You can use (X)HTML. Allowed tags: <a> <b> <dd> <dl> <dt> <i> <li> <ol> <u> <ul>. 'style' attributes will be removed. Newlines will be automatically converted to <br />s if your post doesn't contain HTML or Inline Elements only. Otherwise, you have to insert <br />s and <p>s on your own. Make sure to escape special characters ('<' » '&lt;', '>' » '&gt;', '&' » '&amp;').

see here and here for other examples of useful, concise "filter tips".

If I would not know (X)HTML, the sentence on the automatic br addition would confuse me, and the link to the PHP nl2br() function would only increase my confusion. As far as I can see, the idea behind these tips is to let those people know what they should enter, who don't know these technical things at all...

BTW your explanation of nl2br() is not emitted when the HTML is escaped, though nl2br is still applied in that case. Also imagine if someone is using textile or bbcode "markup", he will not enter any block level element, although block level elements might end up in the output, and nl2br is still applied.

Therefore your explanation is only adequate for a specific configuration. A longer explanation would be needed, which deserves its own page IMHO. I am not against short summaries though, but I do think that clicking on all the links for more information is a serious useability problem.

* i'm aware that it is hard to compress all filter rules into only a few lines. i still think this is absolutely necessary. everyone is invited to suggest better tips and to show tips for the proper configurations ;)
* i don't mind an *additional* long filter tips page
* did you check the first example link of my previous post (additional tips in a hovered "a title")? i really like this idea.

The hover does not work for me in Mozilla, and that hover would not be enough for explaining bbcode or textile rules.

Since there seems to be an agreement that the compose tips should be served by the help hook, and that the core should support compose tips because of the default filters and title filters existing in core, here is a patch that integrates the code from compose_tips.module to filter.module. Some points:

• The new URL for compose tips is filter/tips
• The help hook can add a filter tip with the 'filter#tip' section
• HTML formatting tips are included in filter module (where that filter lives anyway)
• I am going to submit a patch for title.module, in case this is accepted. I also have an outstanding patch for title.module, and would like to wait for the judgement on it too, since the nature of the modifications needd in title.module depend on that patch getting acceptance or not.
• Further improvement/changes are still possible to this system, only the basic integration is achived here, no further improvement is made (aside that the core will have filter tips by default).

Still a task related to Drupal CVS...

I like this patch. A couple very minor suggestions are below. These could be added after the patch is accepted.

- filter_tips() should ideally use theme_item_list() instead of its own custom UL. but then we will use the "compose_tips" id. so in addition, ideally patch to theme_item_list() so attributes may be passed in. sorry about that this patch creep.

- the hard coded "raquo;nbsp;" is undesirable. I know I originally put it there, but I shouldn't have. I suggest giving an id attribute to this paragraph, and either making the &raquo overrideable with theme(), or removing it altogether.

I have thought about letting the filter tips page themeable (theme_filter_tips()), so any theme can reformat it the way they want, but then thought it would be better to provide a simple patch first, and build on it, instead of hacking around too much. We will be able to fix this before the freeze, I am sure :)

I agree with Moshe that the hard-coded markup should be removed. Lastly, I'm not sure I'd want to display the help (or the allowed HTML tags) on a separate page.

Dries, we have discussed this in-and-out above, the current help texts for some filters are long, and will not fit below the form. Therefore a separate page is needed (or separate pages). It was also agreed that the compose tips need to come from the help hook. This patch tries to lay down the base we have agreed on, providing something we can build on.

Shorter helps need to be added to the help hook for short tips, or something else after this patch is accepted, but the basic (and so far proven) approach of the detailed explanation of some filters is just needed because of the complex filters we have...

About the hardcoded HTML, do you think that making a theme function out of the tips page would solve this problem for you? Should we link to the previous page using the referer handling of Drupal and not JavaScript? BTW I think document.writing a javascript link is legitimate, so the backlink will not be printed if JS is not supported, since it would not work in that case.

Reply needed.

I know the compose tips can grow long but I was just thinking up loud and trying to address this usability issue. I prefer to scroll up and down rather than clicking a link and hitting 'back'. Scrolling is faster and depending on your resolution both the form and the compose tips might fit on one screen. By the way, on drupal.org, where I know the compose tips by head, I very much prefer to them to be out of the way, on a separate page. Either way, opening a separate page or pop-up window might be better because some browsers forget the contents of your forms after you clicked a link.

I don't think we need a theme function if you can make the "Writing and formatting tips"-text/link act like a normal form_ description. You would be able to remove the xaquo's as the text can be themed using the theme_form_element() function. The tips page itself should not be themeable as long semantic HTML is used that can be themed using CSS.

What matter to me it the use of raquo and laqou. Fix the theme issues and I'll commit this patch. I recognize it is a great improvement.

(Don't use class="compose_tips" but use class="compose-tips".)

Ok, here is the evolution of my original patch. It also incorporates the form_allowed_tags_text() function, which leads to better concentration of filter related code in filter.module. This function was renamed to filter_tips_short() for consistency. It prints some short info on the HTML allowed and a link to the detailed explanation. Any textarea that might need this tip need to call it and place the retuned text in the help of the textarea (as Dries suggested and as it is done currently in Drupal anyway). :)

Those wanting better short tips will target the _help() hook and the filter_tips_short() function with their patches in the future, given that this patch gets accepted ;)

The forgotten patch...

I applied this patch and noticed that neither the forum module, nor the book or page module show compose tips at the submission form. This is not an artifact of your patch but I figured I would point out this inconsistency. What is more, on my local copy, the compose tips page generates many empty list items. I haven't had time yet to track this down.

Empty list items fixed in this patch. The module_invoke_all() folds the return value of the _help() hook into the array even if it does not contain anything, so we need to check for that... After this patch gets accepted, we need to start a discussion on how to support short tips, so we can add short and long tips to the modules you have mentioned (plus more).

Committed to HEAD. Thanks. I'm marking this 'fixed' but feel free to reopen it, or to start a new issue to discuss the next round of improvements.

(Not sure but maybe we should /fix/ the behavior of module_invoke_all(). I'll look into it.)

Repoening and modifying title as there are a lots of short compose tips ideas here, and it would be a dumb choice to open a new task for this...

As far as I see, the current help hook is reused for many kind of 'message retrieval', like: module descriptions, node descriptions, authentication help, etc... These are not displayed in the regular help form, but are integrated to the _help hook because of their nature of helping users. We have integrated the compose tips for the same reason, using the proven 'filter#tip' format, which means that this is not a regular help.

I think that this hashmark notation is quite simple and is still enough to distinguish between the different kinds of information one can retrieve from the help hook. I am thus not confident that the method suggested by Moshe to provide a type identifier for the emitted help would work. This way every help hook wuold need to hold the URLs possibly displaying textareas where compose tips might be needed (node, project, user signature submit and edit pages, etc), and thus while the filters would be applied to all strings, the tips would not be surely displayed on all pages where needed. I think this overcomplicates the help hooks role...

What I propose for compose tips are the following two simple section identifiers in the help hook: 'filter#tip' and 'filter#short-tip', respectively for the complete tip and the short tip.

Second questoin is the UI. As I have expressed, I think that it is important that one has an overview of all the formatting options and filtering applied to the input she provides. Therefore I suggest going on with the monolithic filter/tips page approach, where all filter descriptions and tips are listed, so one can have a good overview. An opposing idea was that every filter module should have its own filter tip page, which I don't like at all...

It was suggested that textareas should have some short information below them on what formatting is allowed. That would be accomplished with the short tips coming out of the help hooks of filter defining modules as explained above. IMHO these tips should be displayed <br /> separated, or as an item_list below the textarea. Below these short tips, a link should point to the filter tips page (as it is in current Drupal CVS).

So on my site, where the bbcode and glossary filters are turned on, and I have a custom non-degrading email spam protection filter and all HTML disallowed, something like the following would be displayed below a textarea:

No HTML formatting allowed
BBCode tags supported, URLs automatically turned into links
Glossary terms automatically highlighted
Spam protection applied to email addresses
<a .. target="_blank">More information on formatting options</a>

The texts should not be treated as exact suggestions, what I try to propose here is the usage method of the help hook for short tips, and the display of the short and long tips.

Opinions are welcome!

find attached a patch that implements goba's suggestion of the 'filter#short-tip' help section (which apparently i like). i added id's to the <li>s on the filter_tips_page so that short tips can be linked to a more detailed explanation there (as filter#short-tip of title.module in this patch does). i also removed the "target=_blank" - old golden rule: if a user wants to open a link in a new window, she can do so by herself (and there shouldn't be a problem with POST content because of php_value session.cache_limiter none).

this patch also
* contains a fix for title.module generating links from [bla <some html>|<possibly more html>] (this happened on my life site and looks quite bad)
* removes the deprecated title_compose_tips()
* has some doxygen and some s/"/'/g

TODO (not necessary for applying this patch)
* long tips for allowed_html_tags
* integration of Improved form_allowed_tags_text() / doxygen / .htaccess bug fix
* make short and long tips listing themeable

+1 to apply the patch from Ax. BTW Dries suggested that I should include a popup or separate page opener in the patch: "Either way, opening a separate page or pop-up window might be better because some browsers forget the contents of your forms after you clicked a link." I am also on the side of treating the users as intelligent humans, but a lot of Drupal installations might have users who are not aware of what will happen to their somewhat completed form, after they click on that link...

Thanks. I committed a modified version of Ax's patch:

• I did not commit the title.module changes as its short help text did more harm than good. Please use a helpful message and use url() correctly.
• I renamed 'filter#tip' to 'filter#long-tip' to be more consistent with 'filter#short-tip'. I updated the documentation in the contributions repository.
• Made some code improvements.

Since Dries pointed out that some textareas lack the filter tip help in their decription, here comes a patch which adds the description where appropriate. Also removed some lines of duplicate code from comment.module.

Committed Goba's last patch to HEAD. Thanks.