I will post a draft here soon of an announcement giving the whole community a heads-up that the theming pages are going to get shuffled.

In the meantime existing docs team members interested in helping with the effort please

  • post here, if you haven't been participating already in the original thread
  • join Diigo
  • come by the Diigo drupal-docs group and request membership
  • go to the head of the D6 theming guide and play around to test - highlight some text, add a sticky note (don't forget to post it to the group, not leave it private)

I very much want all substantive discussions about the content itself to take place on d.o., and only use Diigo comms for "meta" issues - tagging pages and navigation hierarchy, for now just bookmarks on d.o. theming-related docs please.

Any major issues even on those limited topics will also be posted back to d.o. for feedback, as of course will any workgroup recommendations, before making major changes to the handbook itself.

Comments

HansBKK’s picture

HansBKK commented

moved contents to project page

HansBKK’s picture

HansBKK commented

Brought over from the old thread:


LeeHunter:

Here's a straw man TOC. I'm not suggesting this is the perfect way to structure the handbook especially since I'm definitely a theming noob so I may have got things pretty confused but, speaking as a user, this is the kind of doc approach that I would find most helpful. I'm using a fairly standard documentation model where each section has a brief overview followed by procedures (overviews contain no procedural information, and procedures provide no conceptual information). :


  1. Introduction: Who should read this guide, brief non-technical definitions of theme and theming, brief explanation of what the guide contains and pointers to other documentation (e.g. developer's handbook)

  2. Working with theme files: Brief overview that explains that there are two main locations for theme files and the importance of copying files to a renamed directory. Mention that the reference section has detailed information on the types of files. Mention that there is more information about files in the section on overriding module output. Provide a step-by-step procedure for creating a theme based on another theme. Provide a step-by-step procedure for setting up the files for a new theme

  3. Specifying the layout and presentation : Brief explanation of the role of CSS in theming. Mention Firebug. Clarify that this section only covers how to apply CSS to Drupal output whereas altering the output (renaming classes or creating new divs and classes) is covered in a later section. Brief explanation of the concept of regions. Provide a step-by-step procedure for specifying the regions. Step-by-step procedure for adding a CSS file to a theme.

  4. Customizing a theme for specific pages or sections: Explain that individual nodes, pages, sections can be themed differently. Step-by-step procedures for theming the front page, theming a specific node etc.

  5. Overriding module output: Explain that modules often provide files which can be copied to a theme. Step-by-step procedure for adding the module files to a theme. Step-by-step procedures for overriding output from each of the core modules (especially the common ones like log-in and search)

  6. Working with variables: Brief explanation about what a variable is and where they come from. Explain that a theme can make use of variables from different modules. Mention that the Devel module should be installed. Step-by-step procedure for discovering what variables are in a module. Step-by-step procedure for turning a variable into themable output.

  7. Reference: This would be the bulk of the current D6 theming guide.

Specific feedback welcome

HansBKK’s picture

HansBKK commented

Proposed starting point to the working structure after Addi's merged the various books and branches:

Consolidated Theming Guide

feedback welcome

(edited after pretty thorough googling, rest is scattered, also posted to the project page)

add1sun’s picture

add1sun commented

Ok, we now have one top-level theme guide handbook with the D6 and D5 guides under it. Feel free to begin your work.

Re: the list above of "theme stuff," I'd rather *not* move the BtB: Theming videos and slides into the new handbook, but instead refer to them. The reason for this is that videos are a special medium that some people seek out in particular. I'd like to have one location where people can browse all videos. This strange separation will be alleviated in the redesign when we can tag and build views of thins, thereby making it possible to have the same pages listed in different places (i.e. a video page can be wherever and we can create a view listing all video pages for easy browsing).

HansBKK’s picture

HansBKK commented

OK Addi, same with the other BtB stuff?

* Beyond the Basics: Theme HowTos
* BtB: Theming snippets
* BtB: Contributed themes
* BtB: Comparisons of contrib themes

Just link to them for now, focus on "just" merging/splitting out the D5 and D6, should be enough to keep us busy

I'll set up some standard group tags in Diigo to help with the review process (can be applied at the whole-node level or for specific highlighted text):

D5+6 = applies to both, doesn't need splitting
M5+6 = some applies to D5 some to D6, needs splitting out
D5. = definitely D5 only
D6. = definitely D6 only
D5? = tagger thinks D5 but wants confirmation
D6? = tagger thinks D6 but wants confirmation
D? = tagger looked at it but doesn't know, asking for help

With analogs for D7 and D4-specific stuff we might come across.

The above assumes we agree that within a given topic branch, the parent "main spine intro-overview" pages should be content that applies equally well to D5 and D6, with the version-specific content in labeled sub-pages below. (Let's call this approach A)

An alternative (B) would be to make stuff relevant to D6 the parent, and then give the D5-specific version below. This would require pointing out what in the parent does not work in D5, whereas A only requires discussing at any given level what does work. IMO A also makes it easier for when we're going through this for D7.

Discussion on the above should continue here.

-----
Also, Addi I noticed that this alias remains http://drupal.org/theme-guide/5, which I know was there before, but is this one new? http://drupal.org/theme-guide/6 (if not, then that's where the main http://drupal.org/theme-guide also went)

In any case, only the last one is relevant, both of the others should IMO now 301 redirect to either the last one or we set up a landing page with an explanation.

leehunter’s picture

leehunter commented

I've had a bout of OCED (obsessive compulsive editing disorder) over the past week or so which I think is starting to pass (thank God!).

The main side effect is that nearly all the theming fragments have been gathered in one place and roughly sorted into a set of topics that seem relatively manageable and coherent to me. I've also done some noob-friendly overviews to introduce these topics and written them way down to my level (Hi kids, can you say "hack-er"?).

I'm going to try and leave this alone for a while, but here's what I think still needs work:

- The theme snippets section is a horror show. Just a long, long unsorted list. I'm not sure what to do with this. It probably needs to be treated differently than regular handbook topics. It's kinda crying out for the Views module.

- The overall structure is not too bad but I'm thinking maybe we should just take the four topics under the Drupal 6 Theming Guide heading and move them to the top level. In other words, we make the assumption that people come to theming guide for the latest info and they can still see right away that there's also a D5 book, so maybe there's no need to box up the D6 stuff like this. I can't really make up my mind on whether or not this would be a good thing.

- I don't like the jQuery and JavaScript page very much (http://drupal.org/node/171213). It makes some big assumptions about what I know. For example, in the JavaScript example it reads "The way I would call it is like this ..." and it shows a line of code without telling me, the ignorant noob, where that line actually goes. Those kinds of details would really help new people get started. Because I don't know this subject at all I can't easily fill in those details (at least not without doing more research than I have time for right now). I'd also like see to see a detailed jQuery example.

- I've hardly touched the D5 and earlier section. To me, it's terribly unfriendly and would be much better if it had the same kind of structure as the d6 section. Since the D5 content is starting to drift into the past, I can't get too excited about working with it.

OK I'm taking my meds now.

heather’s picture

heather commented

Hello Lee, re: the 3rd point about jQuery/Javascript page.

I changed the language to follow the Handbook style guidelines, especially regarding pronouns. (guidelines here for anyone else interested http://drupal.org/node/338208 )

I think, as you suggest, someone experienced with jQuery/Javascript should work on the page. I just thought to fix it up a bit.

I should be able to check out more of the themeing handbook changes/suggestions this week, I plan to put in some time to docs queue :)

mistresskim’s picture

mistresskim commented

...maybe we should just take the four topics under the Drupal 6 Theming Guide heading and move them to the top level.

+1 for shifting things up one level but the main categories still need thinking. Perhaps something like:

- Building a Theme
- Theming
- Theme Engines

with the first two containing the bulk of stuff. I think all D5 and D6 content as well as the snippets could be unified reasonably well into that kind of structure once subsections within those could be nutted out. Basically, I think stuff aimed at peeps building fully-fledged themes and content geared at customising/overriding output should be in separate sections.

mistresskim’s picture

mistresskim commented

Lee...I also wanted to ask you about the "Theming without code" page, which I know has been shuffled about back and forth by yourself and Hans.

Personally, I don't think configuring the Display Fields page of CCK, using Views to generate a list of nodes or configuring your theme settings or another module is theming. I tend to think of theming as messing with CSS, template files, theme functions, and of course themes as a whole, but more so at the file level than from a UI. Stuff that can't happen with the flick of a switch.

So I kinda think the stuff mentioned in the TWC page should be rolled into one or two sentences that acknowledge the existence of module UIs to control site presentation and merged with the About theming page. Or the relevant parts used in intros to Theming with CCK, Theming with Views, Configuring your theme etc. Your thoughts?

If you don't mind, I'd also like to rewrite the "About theming" page (and rename it "What is theming?") to make
the line between themes and theming more explicit as well as remove some of the repetition. Should I just have a bash at this or do you already see this page as finished? Let me know.

leehunter’s picture

leehunter commented

How about:

- Working With Themes [Most people are probably going to tinker with an existing theme rather than actually build from scratch. This would encompass both]

- Overriding Themable Output [I think of 'theming' as any kind of theme-related work.]

- Using an Alternative Theme Engine [This would make it clearly that the average Joe doesn't have to go here. Also I wanted to note that we don't have anything yet on theme engines in the D6 section. I'm wondering if that section in the d5 guide (http://drupal.org/node/176129) is still relevant for D6. Anybody know?]

leehunter’s picture

leehunter commented

I definitely think all of this needs way more work so yes, absolutely, all those changes sound good.

Re. the non-theming theming, yeah the only thing I think we need to do is be careful that when we tell people that this book is about "changing the look and feel" of a site that we're not sending a newbie down a theming rabbit hole when they actually just wanted to do something simple that could be accomplished through the UI. So I just wanted to give those people a chance to steer themselves out of the theming guide if it's actually beyond what they want to do. Whether we call it theming or just another way to change the look of your site is not really important (at least as far as I know).

mistresskim’s picture

mistresskim commented

Working with Themes sounds good as the main umbrella. Overriding Themable Output still seems like a mouthful though. Like just because you can make everything an adjective, doesn't mean you should. :) What about Customising Output? Within this there could be subsections named overriding, modifying etc. Anyway I have Internet woes and will be offline for a few days so I will post the new theming intro when I return.

leehunter’s picture

leehunter commented

Yeah I like Customizing Output better.

Some people won't know what "overriding" means until it's explained at least once (or in my case, about six times) and "themable" is probably redundant.

add1sun’s picture

add1sun commented
Status: Active » Closed (won't fix)
Issue tags: +Doc IA

Since theming guide is the guinea pig for the new IA, I'm closing this down as won't fix, though the thoughts and ideas will be considered in the IA.