Closed (fixed)
Project:
Documentation
Component:
Placement/Navigation/Structure
Priority:
Normal
Category:
Task
Assigned:
Unassigned
Reporter:
Created:
30 Dec 2010 at 19:43 UTC
Updated:
3 Apr 2014 at 18:21 UTC
Jump to comment: Most recent, Most recent file
Comments
Comment #1
arianek commentedHi SunKing -
I can't delete those pages, as each has many child pages which would then be orphaned. I will need to know where to move the child pages before those two can be deleted.
Let me know... thanks!
Comment #2
aspilicious commentedHmmm, for me the theming guide looks more like an upgrade guide now.
People going to drupal 7 theming are'nt interested in drupal 6 code.
Why don't we split drupal 6 and drupal 7 theming.
And reference to the same page if the content is the same.
Or can't we use references in the handbook?
Comment #3
arianek commented@aspilicious - a read through #740194: Update theming guide for Drupal 7 should answer your questions here. ;)
Comment #4
aspilicious commentedYeah but http://drupal.org/node/925532 is a dead page....
Comment #5
SunKing2 commentedOk, I'm working on it. I am only now starting to realize that some pages have child pages, and the guide is not as simple as going from the current page to "next", as I had hoped it would be. Without much looking into it, I just wish those pages that don't follow the "next", "previous" navigation would just drop into a black hole, lol. I'll try to follow which pages are child pages of which pages, and hopefully restore the guide so that there's only one way of navigation that makes sense.
Comment #6
SunKing2 commentedOK I think I've followed most of the hierarchy in the theming guide at least until gets to the section on D5, (after which I dare not tread), and I think a little bit of reorganization might be useful here. I'm also changing my mind about deleting the specific page "Theming Drupal 6 and 7" (/themeguide/6-7)
One of my frustrations with the guide originally was how long it took to get to the good stuff. And as I was using it, I found that it was looking like the table of contents for the guide kept changing. Now I know why.
A consistent table of contents requires fewer levels. I'm going to stick with the top level TOC being OK, coz I need some starting point. This has as sections 1. about theming 2. Theming Drupal 6 and 7 and 3. Theming Drupal 5.... and several more... It's not great, but somebody must have thought these were worthwhile sections, so let's keep 'em.
Now what I call page 6 if you following the guide sequentially (p6: Theming Drupal 6 and 7) has child pages and then the navigation gets very confusing. I believe this is because there are too many levels. I'd like to , if you agree ariane, to use this page as the parent page for all of the pages which follow it sequentially, up to , but excluding Theming Drupal 5. So if you are following it sequentially, the page entitled Theming Drupal 6 and 7 should have as sub-pages the following:
1. Overview of theme files
2. Sub-theme structure and inheritance
3. Structure of the .info file
4. Default .info values
[....]
11. Clearing the theme cache
12. Global settings
13. Working with CSS (which should be ok to go another level)
14. Overriding theming output
15. PHP includes in Drupal
16. Quickstart links for D6 themes
17. Template files (which should be ok to go another level)..
that's all.
I can create the subpages manually (by copy paste) if you ok this.
. Instead of deleting it, it should be the main page containing sub-pages that introduce you to theming.
Comment #7
arianek commented@aspilicious - sorry, i've missed where that link came from
@sunking - this seems like a terrible thing to do by hand! i have access to a drag and drop interface for the books. if you can just note what the structure should be here (eg. /node/### "page title") in a indented list to reflect the TOC, i can probably try and rearrange at least the base through there so it's a lot less work for you. then you can do the fine tuning by hand.
best not to copy and recreate pages, as then we lose the links to those nodes from other sections.
Comment #8
jacinesub :D
Comment #9
arianek commentedchanging back to active (forgot earlier!) - trying to drum up some reviews of this proposal from themerly types and docs structure folks...
Comment #10
jensimmons commentedsubscribing
Comment #11
SunKing2 commentedariene, I've figured out the hierarchy of the first 61 pages (all pages which occur sequentially before the d5 section), and I'll work off-line to try to flatten out the hierarchy a bit. Ideally I'd like the TOC to point to child pages which point to child pages but no deeper.
I will get you a list of parent and child pages. I assume that something like the following is what you would need to perform your magic of an " indented list"?? (I won't have the parenthesised parts in the final list)
[NOTE: this is just an EXAMPLE, which i haven't looked at thoroughly yet:]
http://drupal.org/theme-guide/6-7 (parent page)
http://drupal.org/node/337173 (child 1)
http://drupal.org/node/341246 (child2) (see child page below)
http://drupal.org/node/341628 (child 3)
http://drupal.org/node/911762 (child4)
[and more]
http://drupal.org/node/341246 (parent page)
http://drupal.org/node/171209 (child 1)
http://drupal.org/node/778998 (child2)
http://drupal.org/node/744328 (child3)
[and more]
Comment #12
SunKing2 commentedBelow is my proposed flattening of the theming guide hierarchy. Note the first line of each section is the parent page, followed by an indented list of its child pages. At this stage I have not changed any titles. I removed 2 pages from the current theming guide, and they are
Theming without code
Understanding CSS in Drupal
And I realized that the title of this issue implies that I would like to remove 2 more, but I changed my mind. There however, is an existing other issue
http://drupal.org/node/1008312
which requests to move the above pages
/documentation/theme "Theming Guide"
/node/221881 "About theming"
/theme-guide/6-7 "Theming Drupal 6 and 7"
/theme-guide/5 "Theming Drupal 5"
/node/341707 "Tools, best practices and conventions"
/update/theme "Updating a theme to a new version"
/node/22803 "Theme HowTos"
/node/45471 "Theme snippets"
/node/196218 "Contributed themes"
/node/549762 "List of all topics"
/node/549160 "Missing topics"
/node/221881 "About theming"
/node/805968 "Theming options: beginner, intermediate, advanced"
/theme-guide/6-7 "Theming Drupal 6 and 7"
/node/337173 "Specifying theme components and settings"
/node/341246 "Working with CSS"
/node/341628 "Overriding themable output"
/node/911762 "PHP Includes in Drupal"
/node/466206 "Theming with contributed modules"
/node/171213 "Working with JavaScript and jQuery"
/node/337173 "Specifying theme components and settings"
/node/171194 "Overview of theme files"
/node/225125 "Sub-theme structure and inheritance"
/node/171205 "Structure of the .info file"
/node/171206 "Default .info values"
/node/171224 "Assigning content to regions"
/node/517696 "Checking to see if a region is occupied"
/node/221905 "Making settings available to the administration page"
/node/177868 "Advanced theme settings"
/node/864586 "CSS Template"
/node/108459 "Integrating color module"
/node/337176 "Clearing the theme cache"
/getting-started/6/admin/site-building/themes/settings "Global Settings"
/node/341246 "Working with CSS"
/node/171209 "Adding style sheets"
/node/778998 ".clear-block and .clearfix"
/node/744328 "Adding browser-specific style sheets"
/node/225868 "Adding styles through the API"
/node/568180 "Creating and rendering CSS templates (eg. style.css.php)"
/node/263967 "Overriding style sheets from modules and base themes"
/node/388372 "Standard Drupal core styles and classes"
/node/222782 "Supporting "right to left" (RTL) languages"
/node/341628 "Overriding themable output"
/node/457740 "Beginners guide to overriding themable output"
/node/348916 "Introduction to PHP for theming"
/node/173880 "About overriding themable output"
/node/223430 "Setting up variables for use in a template (preprocess functions)"
/node/226776 "Default baseline variables"
/node/350634 "Customizing and Overriding User Login page, Register, and Password Reset in Drupal 6"
/node/581786 "Example: Themable output"
/node/778900 "Identifying Core Components"
/node/778884 "Core Block CSS IDs"
/node/779016 "Mission statement and highlighted region"
/node/778906 "Navigation"
/node/778922 "Taxonomy"
/node/778926 "Unrendered taxonomy links no longer available as a separate variable in node.tpl.php files"
/node/988842 "Menu theming"
/node/988694 "Overriding a menu in a block"
/node/223463 "The theme registry for special cases"
/node/223440 "Working with template suggestions"
/node/190815 "Core templates and suggestions"
/node/171188 "Architectural view of theming"
/node/911762 "PHP Includes in Drupal"
/node/587366 "Quickstart Links for Drupal 6 themes"
/node/778940 "Template Files (tpl.php's)"
/node/779002 "box.tpl.php"
/node/815828 "node.tpl.php"
/node/778954 "page.tpl.php"
/node/778988 "Implementing RDFa"
/node/778956 "page.tpl.php variables"
/node/466206 "Theming with contributed modules"
/node/626578 "Example of Theming a pinboard with custom node-type and module Views"
/node/825218 "Theming with Browser Theme Settings"
Comment #13
arianek commentedthat's great sunking! i think i should be able to follow that relatively well to move the book pages.
i'm going to email leehunter and see if he can give his 2 cents on the proposed page order, since he's been working the most with the handbook structure.
if anyone else wants to give input, speak now ;)
Comment #14
wfx commentedGreat work! I like the structure and I think it will be easy to follow by most people.
Comment #15
jacineIt looks like you want to flatten all these and move them under "PHP inclues in Drupal. I'm assuming that just translated wrong in the post?
Anyways, hopefully that's helpful in some way. So much has changed from Drupal 6 to Drupal 7, and having to explain both side-by-side is going to be extremely hard, and in many cases impossible without confusing the crap out of people.
Comment #16
leehunter commentedBasically I think this structure looks pretty good. Here are a few random thoughts:
- The Drupal 5-specific content can be removed now, which means that we should have a new heading for "Theming Drupal 6 and 7" since the "6 and 7" was only there to distinguish it from the D5 stuff. Or maybe, and this might be a better idea, we should just get rid of this heading completely and move everything under it up a level. This might make for a lot of top level headings but it would help flatten the hierarchy and expose more stuff to the reader.
- There are some minor things that need some work (i.e. can be cleaned up later) For example, "PHP Includes in Drupal" is not a great heading since most new users wouldn't have a clue what it means (or at least I didn't get it). The content on that page would also have to be rewritten if it was to be used as the container page (i.e. should just be a brief explanation of what content will be covered in the section). I wonder if this heading might be something like "Reference: templates" or "Template reference" since it's really more of a reference section than a how to.
Otherwise it looks great to me.
Comment #17
SunKing2 commented@Jacine - I'll be looking at all those pages in the next few days, and see what can be done.
@LeeHunter - Ya, I kinda like that idea of moving that stuff up a level.
Some of those pages are pretty short, and having a slew of page titles in a "table of contents" doesn't look that good. Maybe I'll look into titles, and maybe combining some pages so their titles look good in the TOC.
I never did really like having to go to a page which is just a list of topics and going down another level... kinda frustrating for the user; but one fire at a time. I'll look at the other comments, Lee, from you too over the next few days.
Comment #18
arianek commentedHey........
So just following up here (and a note, we're not deleting the D5 content quite yet, just following up to get a decision on that with Dries, Addi, and some others (keep an eye on http://drupal.org/node/1026542 if you want to follow that discussion). That said, I think moving the main theme guide up a level is a great idea and not dependent on that.
I think Jacine's (awesome, thanks for the review!) comments can mostly be addressed as a second round, as some are edits that can be done by anyone. Though the PHP includes reorganizing I can do. So I think we can do the first massive reorder and then do some tweaks based on her comments once that's taken care of.
I've got another writing deadline in a few days, but if we can get consensus on the main big page shuffle over the course of the next week, I could probably work on reordering things next weekend.
Comment #19
Carolyn commentedI changed the notes at:
http://drupal.org/node/337173
http://drupal.org/theme-guide/6-7
to link to this issue. This seems to be the most recent discussion on the organizing the theming guide. I also wrote a little intro text on those pages.
Comment #20
Danic commentedExactly! What do I care about D6 when theming D7 and vice versa?
And it's confusing.
Comment #21
leehunter commentedI totally agree that the desired end state is to have the reader *see* d6 and d7 (and soon d8) guides as separate... but it's really important that we don't do this the wrong way (i.e. by trying to maintain two or three entirely separate versions). Because much of the content between the two versions is actually identical, the only sane and sustainable approach is through single-sourcing (which means that any chunk of content only physically exists in one location, but can be displayed in one or many guides). That serves the reader's interest in seeing only the relevant version and it makes the content much easier to maintain.
The alternative requires forking the content between deliverables and it quickly becomes a maintenance nightmare. Imagine if a chunk of content has a mistake - if there are separate instances for D6, D7 and D8, you've just *tripled* the workload (although usually what happens is that it only gets fixed in one instance).
We haven't quite worked out how we want to do single-sourcing in d.o. but I think we're very close. Now's not the time to fork content.
Comment #22
arianek commentedIndeed - bear with us! If anyone wants to follow or help out with the issue that will solve this, it's: #995362: Conditional Text ability needed for book pages
Comment #23
mparker17I don't know if I should report this here or in a new issue; but following the
[Docs updated]link in the "The box.tpl.php template has been removed" section to http://drupal.org/node/779002 isn't currently working... I get a 403 Access Denied error when I try to view http://drupal.org/node/779002This happens for anonymous users too.
Comment #24
mparker17Whoops... looks like I changed the component accidentally. Sorry everyone!
Comment #25
arianek commentedmparker - can you post that as a separate issue and tag it "docs admins"? thanks!
Comment #26
mparker17@arianek: Done: #1254236: 403 Access Denied when trying to view node 779002.
Comment #27
leehunter commented