[wp-trac] Re: [WordPress Trac] #8799: get_search_form() is inadequately documented

[WordPress Trac]

#8799: get_search_form() is inadequately documented
----------------------------------------------+-----------------------------
 Reporter:  sampablokuper                     |        Owner:          
     Type:  enhancement                       |       Status:  reopened
 Priority:  normal                            |    Milestone:  2.8     
Component:  WordPress.org                     |      Version:  2.7     
 Severity:  normal                            |   Resolution:          
 Keywords:  search theme documentation codex  |  
----------------------------------------------+-----------------------------
Changes (by sampablokuper):

  * status:  closed => reopened
  * resolution:  wontfix =>
  * milestone:  => 2.8

Comment:

 Replying to [comment:6 jacobsantos]:
 > Whoever said searchform.php was deprecated was wrong. It is not
 deprecated in 2.7. There was some complaint about deprecating
 searchform.php, so even if the word on the street was that it was being
 deprecated, it ended up not being deprecated.

 I guessed as much in the end, but it's good to have it clarified by
 someone who knows the background. This removes the uncertainty that
 inevitably surrounds a guess.

 >The Trac people and the Codex people do not often talk to each other.

 Now ''THAT'' is an A1 bug!

 > As for examples, I would have to give an sarcastic reply, "Do you want
 us to wipe your ass as well?" Yes, examples would be an nice addition.

 No need to be so rude, especially as I didn't ask for examples.

 > The whole issue is that, there are two ways for a '''theme''' to change
 the search form on the widget

 Those two ways being:
  1. Create a searchform.php file if one doesn't already exist.
  2. Use a filter in functions.php.

 OK, I get the drill now.

 This stuff needs to be made clearer in the Codex. The assertion I made in
 the title of this ticket remains true.

 >and if the user hard codes it. You don't need to create a plugin and in
 this case, it is better if you don't.

 Agreed.

 > I think the wording is arbitrarily,

 If you mean "ambiguous", I agree with you. It is ambiguous.

 I don't think ambiguous documentation is a good thing, and I think most
 users and developers would agree with me.

 > Wording: A little vague, but the summary works.

 If it worked reliably, I wouldn't have had to open this ticket.

 I get the impression that what you've said about Trac people and Codex
 people not talking to each other (I'd put characterise it as, "not getting
 involved in each others' work") is holding true in this case. Yet at least
 since "Zen and the art of motorcycle maintenance" was published (1974),
 it's been clear that developers and documentors need to work closely in
 order to be effective together. It's also clear that they are rarely
 terribly effective separately.

 Anyway, even though the thread above should provide sufficient help for
 someone searching on this problem to be able to solve it, Trac isn't the
 first place they should be finding this help: the Codex is. So until all
 the knowledge that's been laid out in the posts above makes it into the
 Codex, surely this ticket should stay open. I'm not being ornery. If I
 find time, I'll update the relevant parts of the Codex myself. But until
 it ''has'' been updated, I believe this is a valid ticket.

-- 
Ticket URL: <http://trac.wordpress.org/ticket/8799#comment:9>
WordPress Trac <http://trac.wordpress.org/>
WordPress blogging software