Incorrect filter documentation

Changed the component to reflect the new component categorization. See http://drupal.org/node/301443.

Subscribing - I just spent quite some time trying to figure out why the escaping wasn't working anymore.

Is the procedure for updating docs in CVS just like with core - do HEAD, then backport as needed?

Here is a patch against HEAD which addresses this issue. It changes the following:

1. Set's the settings fieldset to be expanded by default. Every filter module I've used, including those in core, default to expanded, so I don't see why this should be different.
2. Adds a note about how disabling caching for a filter disables it for all filters in an associated input format.
3. Updates the escaped text to [filter_example-time] for the time filter. In the comment I link to the handbook page, but I don't know if there's a better or proper way to do that.
4. Replace REQUEST_TIME with a call to time(). The module wouldn't have worked unless register globals was enabled.

The only other suggestion I could make is that there is no mention of the .info file which exists in CVS. For those new to Drupal, not having a link to that would be very confusing for those attempting to run the code. I'm guessing this is more of an api.d.o infrastructure task though.

drewish just pointed out to me that REQUEST_TIME is actually a new D7 feature - should have noticed that the D6 module page uses time().

Here's an updated patch - when it's ready for backporting, remember to replace REQUEST_TIME with time() for D4.7-6.

Is there any reason we mix underscores and dashes in [filter_example-time]? Let's make this consistent and set the right example in ... example code. :-)

I was following the convention as documented at http://drupal.org/node/209715, which seems to indicate that dashes should be used between the namespace and the filter. I can update both the patch and the page to indicate that underscores are preferred, but that dashes are allowed.

Also, I just noticed that the handbook page example uses [modulename-tag] for the opening tag and [/tag-modulename] for the closing tag. Anyone know if there is a reason why the order is reversed in the close tag?

Can't you update the patch to just use dashes?

Sure, as long as we're OK with the module name not matching exactly. Patch is the same as above, with the tag set to [filter-example-time].

I believe the last test failed because it tried to apply it to core. The patch still applies cleanly to the documentation project.

Can you provide a patch for CVS HEAD too?

The patch in #8 is against /cvs/drupal-contrib/contributions/docs/developer/examples/filter_example.module HEAD, unless you mean HEAD on some other path?

The documentation now lives in core, and no longer in contrib. I was referring to core HEAD. :)

Here is a patch implementing the same change against the hook documentation. The above patch is still needed for filter_example.module though.

Both patches look good. Testbot didn't like the first one because it cannot account for the drupal-contrib repository, but the patch applies just fine.

However, a caveat: The forbidden high-bit characters were used for a reason. What happens if I write [codefilter-code] into my comment manually? Can we afford not to check for conflicts in input?

Committed to CVS HEAD. Thanks!

Here's a patch against DRUPAL-6--1-1 based off of the patch from #2. Will this also need to be ported to D5?

I just noticed that the handbook page example uses [modulename-tag] for the opening tag and [/tag-modulename] for the closing tag.

I made the change just now. Not claiming that the docs at http://drupal.org/node/209715 are now 100% correct, but if you see something that should be changed in documentation, just make the change and we can revert back if necessary.

#19 still applies cleanly; it would be great if someone else could review and consider marking as RTBC.

That last patch is against the filter.example module. Example modules have been moved into a different repository, so if you want to get something changed in that example, please file a new issue against the "Examples for Developers" module. I'm not going to move this issue over to that queue, because that would sort of negate the history of it being a fixed D7 core issue.

The patch that was applied in D7 from #14 changed the filter hook doc though. Do we need to do the same for D6, or did someone already do so?

I've opened an issue over in the examples contrib module over at #709376: Don't use invalid UTF characters for the example time filter. This should probably be fixed in the D5 documentation as well.

And here is a patch against DRUPAL-5.

Um. Was there a patch/commit for Drupal 6 to fix the hook doc, like what was done in #14 for Drupal 7?

It looks like http://api.drupal.org/api/function/hook_filter/6 for Drupal 6 has not been updated yet. So I'm setting this back to Drupal 6.
It also looks like the filter example for Drupal 6 has not been updated either -- http://api.drupal.org/api/function/filter_example_filter/6 ? Although the issue on the Examples project is marked as fixed for Drupal 6.

But I could be wrong... Can someone verify?

Actually, it looks like the filter example module was updated, but api.drupal.org has not caught up with it.

But the hook doc for D6 has not been updated. That is in the contrib repository in the developer docs section.

Agreed.
http://api.drupal.org/api/function/hook_filter/6 is wrong.
http://api.drupal.org/api/function/filter_example_filter/6 has been fixed.

I have just updated the hook_filter() example in the D6 docs contrib repository, using the patch from #14 that was accepted for D7 as a model.

We aren't maintaining the examples for developers in Drupal 5 any more. We could port this fix to Drupal 5, but I don't think it's a very high priority. If someone wants to, use the patch in #14 as an example, and the code is in the contrib repository.

7.0 is out tomorrow, 5.x is obsolete, won't fix, sorry.