[documentation] [task] Clarification needed for "Converting 4.6 themes to 4.7" (?)

[laura s]

Issue status update for 
http://drupal.org/node/42110
Post a follow up: 
http://drupal.org/project/comments/add/42110

 Project:      Documentation
 Version:      <none>
 Component:    Developer Guide
 Category:     tasks
 Priority:     normal
 Assigned to:  Anonymous
 Reported by:  laura s
 Updated by:   laura s
 Status:       active

Re http://drupal.org/node/25297


"To upgrade PHPTemplate-based themes, the minimum change needed is to
add a "header" region to the page.tpl.php file (a region below the top
of page banner). In bluemarine, the added region looked like this:


  <tr>
    <td colspan="2"><div> 
<?php print $header ?>

 </div></td>
  </tr>


See the page on regioning in PHPTemplate themes for tips on how to
introduce your own custom regions.

"
While the table tags are a clue, this bluemarine example might be a bit
unclear, especially when "header" is so similar to the "head" of html
pages. For many phpTemplate themes, the header is not within the table
... or there are no tables at all. Perhaps a more generic example like:


"To upgrade PHPTemplate-based themes, the minimum change needed is to
add a "header" region to the page.tpl.php file (a region below the top
of page banner), as such:



<?php
 print $header 
?>




/Note that for table-based themes, you may want to place this code
within a table cell. For example, in *bluemarine*, the added region
might look like this:/


  <tr>
    <td colspan="2"><div> 
<?php print $header ?>

 </div></td>
  </tr>


See the page on regioning in PHPTemplate themes for tips on how to
introduce your own custom regions.

"
Is that perhaps clearer?


*Also, on the same page* (so I'll keep this in the same issue):


"Like plain PHP themes, template engines besides the core PHPTemplate
one can be minimally upgraded simply by adding a
mythemeengine_regions() function defining the already-available left
and right regions. But full support for regioning will require more
extensive changes. The phptemplate.engine section of the
recently-applied regioning patch should be a partial guide for what's
needed.

"
This paragraph is unclear to me. Could someone maybe clarify with an
example, or, if this isn't the place, should we create a child page or
point to an existing page elsewhere with a clearer description? It may
seem obvious to those who already understand this theming information,
but to me it's not clear what this is -- something for the
page.tpl.php? something for template.php? 


I'd write it myself, but I don't know the answer. All this tells me as
a theme developer is to go look at a patch to decipher its intention,
which is not ideal for a handbook, and that otherwise that I'll have to
find the info I need elsewhere. As it is, only people with rather
intimate knowledge of phpTemplate's pre-processing of data would
understand what this paragraph means. As we want more people
contributing more and better themes to Drupal, my feeling is that we
strive to make the handbook instructions clearer for less code-savvy
designers, especially for phpTemplate, which is supposed to make
theming so much easier (and really does, too). 


For myself, I'm catching up on the 4.7 changes and I'll figure it out,
so while I'd certainly benefit from a clearer explanation, this
request/suggestion is more for the benefit of less technically-adept
designers. If nobody gets to this sooner, I'll take a stab at this, too
... once I know what it's all about.


Thanks.




laura s