What would an “ideal” theme guide look like?

I have a hard time wrapping my mind around the structure of the current theming guide. This makes it difficult to work on the guide or update it for D7. I'd like to talk about what an ideal theme guide might look like, as something to move towards.

This is a rough idea of how the Theming Drupal 6 and 7 guide might be re-structured. This outline assumes that readers know intermediate-level HTML and CSS, but may have little to no knowledge of PHP.

Audience: designers and front-end developers

Theming Drupal 6 and 7 →

• Anatomy of a Theme

  • .info file (defines theme files)
  • tpl.php files (markup)
  • css files - (presentation)
  • template.php (logic)
  • Building a basic theme
    • .info file
    • page template
    • style.css
  • Customizing template files to control your markup
    • page.tpl.php in-depth
      • variables in page.tpl.php
      • creating regions
      • digging through arrays
        • using devel_themer
    • node.tpl.php in-depth
      • understanding the $content variable
    • How to add more template files
    • Theming specific content types with templates
    • Theming specific nodes with templates
  • Default markup and styles
    • How modules add HTML and CSS
      • Why there are many stylesheets
      • Why and where templates are created
    • Core templates
      • D7 template suggestions
      • D6 template suggestions
    • Standard core styles and classes
    • Viewing default markup with Stark
  • Subtheming
    • How subtheming works
    • Starting with a base theme
      • comparison chart of starter theme features
  • Caching
    • clearing the theme registry
    • clearing the cache
    • css and js aggregation

• Advanced theming

  • Theming Views
    • Semantic Views
  • Theming Panels
  • Theming Fields
  • Theming Forms
  • Altering Forms with the FAPI
  • example: changing the search button text
  • Javascript and Jquery
  • Creating advanced theme settings
  • Creating UI settings with Skinr
  • Theming for different devices
    • Mobile themes
    • Targeting devices with Mobile tools
    • Targeting browsers
      • e.g. adding ie7 fixes
    • print stylesheets
    • rtf languages
• Custom Theming with PHP Functions
  • resources for learning PHP
  • Intro to the Drupal API
    • theme functions in modules
    • the theme() function
      • inheritance of functions
      • theme() function vs. template files
    • t(), drupal_get_path, etc.
  • A few theme examples with extensive commentary
  • Creating new variables
    • example: for a page
    • example: for a block
  • More PHP functions

• Best Practices

  • Where to put theme files
    • sites/all/themes, etc.
  • Security in the theme
  • Keep logic in template.php
  • Theming methodology
    • Sustainable theming
    • Limiting template files