Clarification needed for "Converting 4.6 themes to 4.7" (?)

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:

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.