Filtered HTML Help Tips

Thanks for taking the time to take a look and comment, Steven. I appreciate your feedback. My intent was to provide "kinder, gentler" documentation for those that may be less familiar with HTML than you and I. Of course I need something similar to this patch for my own site's users but I think addressing something so simple as help text would help address usability comments. Dan Gilmore is a reasonably well respected journalist.

1) The reason I checked in my patch to my sandbox is that the README.txt file is one of two files specifically mentioned in my new CVS account email from Dries, . Thanks for confirming that using sandboxes for patches is deprecated. Can you or someone else please update the README.txt file?

2) I'll work on a new patch that has help text for each specific tag and shows them if they are configured for use. I'm thinking that a system similar in nature of how the filters show their own text automatically should fit the need. My short term goal was getting something into Drupal that gave more feedback than is currently there and to begin the discussion about the contents.

3) After checking each entity I found exactly one that's missing a semicolon. My aspell also found I had mispelled one word: hexadecimal. Do you see others? Thanks for catching those mistakes I made.

4) Regarding the use of entities, my goal was to provide simple instructions that any drupal user can use to input text they would like. I would be happy to use any alternative text you or anyone else can provide. Since using entities is fully supported by current web specifications and Drupal end users who know HTML might want to use them I thought that including them would be best. Additional text about directly entering UTF text is not something I've extensively tested across browsers and Drupal versions. I feel that whatever works should be included in these instructions somehow, allowing the users looking for help in entering text to understand their options.

5) I chose the help structure to exactly match the order of tags used by my default installation. I agree that a better structure and <pre> blocks would work better and be more clear.

Other similar types of projects have attempted to teach their users end HTML (or other markups) such as TWiki.org's descrption and table. Layout wise (not content since it's TWiki specific), do you think either of these examples is helpful?

6) The reason I chose to propose linking to builder.com is because it had useful beginners guides to HTML. "Unofficial" or not it has helpful information. Terse w3.org specs are less helpful to people that may potentially be less familiar with standard HTML tags and their use, but of course not including them would be a gross omission for those wanting to understand the details and for more experienced Drupal end-users. If we write other guides or have alternative sites that help beginners to learn HTML then we should, of course, include those instead.

7) The next version of this patch will include only one space between sentences.

Thanks again, I'll work on the code necessary for a dynamic help system for each tag in the list. I would appreciate feedback from anyone who proposes specific text for each tag. I would also appreciate some feedback from those that will make the decision on whether to apply a future version of this patch.

Here's a new patch against the latest CVS that should address the concerns raised previously. I've also updated the HTML demonstration page. The alternating light and dark classes for the table rows doesn't show for the pushbutton theme. Comments welcome.

OK, this patch is coming along. Comments welcome.

- Thanks for the regular expression, it works great.

- The order of the tips is purposely in the order provided in $allowed_html. Consistency of order is a good thing for those not very familiar with HTML. It allows anyone to know to find a particular tag near the top or near the bottom of the table based on the order displayed by the string. A fixed order would take away flexibility easily afforded to site administrators and impose truly arbitrary ordering with no way for a site administrator to change it.

- The table theme functions are extremely nice. I used the two examples in the forum.module as guides.

- Thank you again for pointing out two spacing and a couple capitalization errors. I fixed as many as I could find. I am sure you can fix any I miss if you choose to accept some version of this patch.

- The array arrangement is much nicer and is required for using the table theme functions.

- I snuck in one more drupal_specialchars() call lower down. I know it's preferable to keep patches of different functionality separate but it was just one. I originally used the existing coding convention used in the file.

- I reworded the entity description. I hope it makese more sense. The point of help instructions is to provide as much concise information as possible about functionality that works in practice regardless of what should work or ought to work. I would also love to see every system on the planet using UTF-8 as a standard character set out of the box, though I have heard on good authority that even UTF-8 doesn't cover everything yet. I think reality will take awhile to catch up; lowest common denominators, like good old 7 bit us-ascii that's identical in most character sets, will need to be allowed until it does.

- Moving to the table functions eliminated the need for playing with CSS.

I understand all about coding standards and preferences. Each project has their own standards for very good reasons. I'll keep submitting my first patch until I learn the ropes. I greatly appreciate your last comment, giving me some indication that this patch will be useful at some point.

v4. Happy Holidays.

The current code provides users with only the tag list. This is not very helpful to those that don't understand how to use tags. I'm trying to a) improve my own site and b) improve the Drupal end-user experience for ALL users. Online help text is a key way to provide support for users. The tips are specifically focused on HTML tags that are available. Tips for other filters should be added to the other filters. My first patch was specifically similar to the existing PHP filter example. Providing additional links for those that want to dive in won't hurt the user experience of most and will aid those that would like additional detail of what they can type in their own text entry box.

I believe examples, given in the context of the way readers of the page want to use them, are the clearest way to explain any new concept, especially to those without prior knowledge.

I hope people can weigh in sooner (rather than later) with specific alternate examples of what they would prefer to see so I can respond. Changing the link from Drupal to the site's own URL is simple enough after I find the right variables. Rewriting to remove mention of Drupal and use "this site" should not be hard. More text about the concept of character encoding seems appropriate. Adding the use of drupal_specialchars() instead of duplicated data in the array is easy enough.

I'll keep submitting my patches (after Christmas) until this goal is reached, balancing all input until there is agreement among all interested parties. Short term I will (of course) incorporate the outstanding items mentioned and we will see how close we are to an acceptable result. Comments encouraged.

For review.

Thanks to Dries and Steven for the IRC discussion today. I think this patch addresses most of the issues. We also discussed adding a toggle to function _filter_html_settings to disable the help text, useful when the HTML filter is used along with other filters and modules like htmlarea, textile, etc.

One concern about this patch was about bloat. Are there others that share this concern about this patch? Comments welcome.

I realize end-user text like this is rather dry, but for end users that need it the value is fairly significant. This version works with the <h1> type tags, changing from [a-z]+ to [a-z0-9]+ in the regex.

Obviously I do not feel this patch is bloat. I don't think it is extraneous to help users (of various levels) understand how tags look in whatever theme they are using, but I do understand the concern. Changes to the text could be might make this long filter tip work better in more complex scenarios where this is not the only filter in use. This might also minimize the need for (and would be easier than) a special toggle.

More additional requirements met (like proper use of t()) after IRC discussions. I've also updated the sample at http://softwaremanagers.org/filter-tips-sample.html Comments welcome. Happy New Year!

Changed text for tag, removed " and for named anchors on the same page." since it won't work as people expect it to due to drupal's tag.