Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
By cel4145 on
In order to improve Drupal documentation usability, the Drupal handbook has been undergoing significant revision and feature enhancement:
- Longer handbook pages have been broken into multiple pages so as to allow the collaborative book to generate all section headings.
- Drupal handbook pages have DocBook XML and OPML export functions.
- The admin/help text available with Drupal core installations has been updated to include 60+ core and contributed modules (patch pending). Admin/help text will now be maintained on drupal.org in the modules and features section of the handbook.
- Handbook pages on drupal.org have additional blocks available in the sidebar providing useful links and information on handbook usage.
- Advanced Drupal users are providing additional configuration tutorials and code such as best practices and PHP page snippets.
- Based upon the user feedback gained in the recent card sort exercise, the Drupal handbook is being completely reorganized into multiple handbooks.
The last of these, the reorganization of handbook pages, is currently in progress. Drupal users will find the handbook has now been split into 5 books. Users can expect that all legacy links to handbook pages are being preserved, but that sections of the handbook may be in different locations than before as we complete reorganization.
Anyone interested in contributing to this reorganization process should feel free to get involved.
Comments
Idea
I'd sure like to see a PDF export option, too - with bookmarks for page locations.
PDFs are available
PDF versions of each handbook are now available:
http://www.puregin.org/Drupal-handbooks
It's possible in principle to generate PDF on-the-fly via the DocBook stuff I'm working on. However, this will likely be quite a CPU hog, so I don't anticipate much support for this feature.
PDF via cron
Instead of generating PDFs on demand, how about on cron run? Since books contain mostly static content (as opposed to blogs or forums) I think it not being up to the minute (but rather, up to the hour) would be a reasonable trade off.
why?
Why do people want pdf's the the various text formats work nicely? In any case, I doubt pdf generation could implemented any time soon. PDF generation certainly has a hit to the CPU performance of the server.
-sp
---------
Test site...always start with a test site.
Drupal Best Practices Guide
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide
I think, familiar formats
I think, familiar formats such as XML or PDF should be optionally included. Why is it that much concern to you what the CPU does? Maybe I've got a dual processor server and my visitors prefer tosave the materials for later printing/reading/sending. PDF has the plus that the format is available on multiple platforms (including mobile), thu sdoes not need any converter. Also to fix the design on a specific layout is another nice plus, as design is important on bigger cpompany portals/intranets, they tend to use the same design everywhere and PDF gives us the advantage that it is fixed.
Of course this PDF-ability should be applied as an add-on, so CPU-concerning people could use the same functionalities.
This leads me to thinking of pluginnable book-pages, where you can add-on features such as XML or PDF or change the design of the pages as it can be done in FlexiNode. Just thinking loudly, could be interesting...
Anyway, there are people who like some features and CPU's sweating is not our concern. I pay for my hosting, therefore I have the right to use it for the sake of my project. Crontabbing is really a nice idea, with addition to not double-generating already generated pages. Indexing of the site works the same way, it does it only once. So to generate 50-100 pages, 5 in each run and then stops for a longer period would nt be THAT CPU-intensive...
performance
Because CPU performance impact is at pdf generation time and that performace hit would be on drupal.org. Drupal.org is already impacted, so I care becuase my day to day browsing experiance is important to me. So cpu's sweating is our concern.
-sp
---------
Test site...always start with a test site.
Drupal Best Practices Guide
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide
Openminded
I hope I'm just misinterpreting your comment, but you make it sound like core modules aren't allowed to have features that wouldn't be used on drupal.org.
My users don't know what XML and OPML are. They're ordinary, non-technical people and the current export links confuse them. I would like to have configuration option to turn on PDF output and have XML and OPML turned off.
I'm not sure that the cron idea is the best. I understand the CPU issue, but if you want a node and all its child nodes, you'd have to generate a lot of different PDF files for each level of the book to cover each available starting top node in the book.
I don't expect to see PDF output soon simply because of the CPU/diskspace/generation time tradeoffs, the probable complexity of formatting the PDF output, and low demand for PDF output - but it would still be nice to have.
the thread started with
Why can't we have PDF autogeneration on Drupal.org. I was repsonding to....
As to the rest, I have since chatted in #drupal-support with one gentleman who expressed his frustration with not being able to find a suitable library for generating UTF-8 PDF's. Now I know nothing of PDF generation through php, nor am I interested :).
You on the other hand are certainly welcome to go nuts submitting patches for hooks into core to do this if it scratches your itch and someday I may suddenly have a need for this feature. .
-sp
---------
Test site...always start with a test site.
Drupal Best Practices Guide
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide
Good point re: configuration
deekayen, do you think that having various export options configurable this via permissions would work for your situation?
I've been thinking about how to avoid cluttering the interface and overwhelming users with choices... suggestions and ideas would be greatly appreciated!
Djun
Certainly possible in principle
Both on-the-fly and cron based PDF generation will be possible. I can see that this might be useful for certain projects/sites (though probably not Drupal.org!)
Just to give some sense for how compute intensive this process might be, here's some benchmarks: on my server with Dual 2.8GHz Xeon 800 FSB, 1 GB RAM, SATA drive, the 600 nodes of the Drupal handbook (July 4 2005 edition) took about 6 minutes to download, pre-process, and convert from HTML to PDF. About 5 minutes of this time was spent on the actual HTML to PDF conversion.
Exporting DocBook and converting to PDF will likely not save time, because each node will require normalization via HTML Corrector or Tidy, followed by an XSLT transformation. The aggregate XML document must then be run through FOP or another converter to produce PDF. These converters tend to be written for standards compliance rather than speed.
Unless we find some way to cache PDFs, this is going to be too demanding for all but a very small, specialized set of applications.
--
puregin
PDFs are cached!
The argument about the cost of PDF generation is just silly. It can be done as a nightly activity and the result cached. There is definitely no reason to do it on the fly.
I agree that doing it on the fly would be a serious CPU burden. We're doing automatic document generation from source every time we rebuild the old (static) coyotos.org site. It takes 30+ minutes, and the majority of that is latex time to get the PDFs generated.
And before somebody suggests it, FOP was slow enough and buggy enough to be utterly useless for us.
ahem
Thank you for jumping in here with your inciteful commentary.
As you are new, you are lacking some information that made PDF generation at ANY time a problem at the time when this issue was posted. At the time, the server could not handle ANY additional load at ANY time. We have since been mgrating to a new server infrastructure in the last few months. That work is still ongoing.
In any case, your comment about 'nightly activity' misses an important point.... which timezones night?
Also, at the time, the handbook module was not very easy to export data from to automate such a conversion. The hanbook module needed a lot of work to position itself for this. puregin has done a lot of that work since.
-sp
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide
Thank you
Indeed, I did not know the history. My thought was that the handbook was a special case of a more general problem: well-formatted, printable output. I think that the general problem is the right one to solve if this feature is of interest.
As to which time zone: it doesn't matter. What I was trying to say is that it is probably acceptable for most uses if PDF generation is viewed as a scheduled, "offline" activity rather than a computation that occurs interactively on request. Better still would be to let it occur on request but then cache the result, but I suspect this would not interact well with the transactional time limits in PHP.
Thanks for the clarification about the handbook. It raises an additional question, but this is purely for my own curiosity:
You say that the handbook was done in a handbook module. I'm sure that there was a good reason for this. Given Drupal today, if the luxury existed to rewrite the handbook from scratch, would it now be practical to do it without a custom module?
there are maybe 10 of us who
there are maybe 10 of us who actually work on the handbook at any given time on a regular basis.
The book module has built in structural controls and all the neat content type export features that make it really useful. Also, additional permission levels are being added for future stuff books and control that are really neat. The next/previous page stuff, autogenerating menu tree/breadcrumbs. For what it does, I think a specialized module makes sense.
Note, that's only my opinion though. :)
-sp
---------
Test site, always start with a test site.
Drupal Best Practices Guide -|- Black Mountain
-Steven Peck
---------
Test site, always start with a test site.
Drupal Best Practices Guide
Lost
Hello there.; some initial feedback
I like the ide alot. And I decided to look up my favorite section: The theme developers handbook.
I got it right the first time! Great work.
Bur from there I was lost. I wanted to visit my other favorite "custom blocks reopsitory"
There is no "way up". Ther breadcrum does not ead me back to "/handbooks", the "up" stops at the root of a section and the sideblocs give me no indication how to move "sideways" to the "configuration" sections of the handbook.
The only way, is to klick the "handbooks tab" or use the back button.
I know this is not a problem with your design, but that it is rather a flaw in the design of book.module.
Here aer some things that should be chabnged in the module IMHO.
* use /book for root,
* include "handbooks" in the breadcrumb
* Include a block with available book-roots.
Or, -and now i'm playing the devils advocate- you could choose to move the different sections under one root, called "handbooks"....
---
if you dont like the choices being made for you, you should start making your own.
---
[Bèr Kessels | Drupal services www.webschuur.com]
Issue in issue tracker for this project
I found this out only after I already posted here. Others might prefer to discuss improvements in the dedicated handbook issue.
---
if you dont like the choices being made for you, you should start making your own.
---
[Bèr Kessels | Drupal services www.webschuur.com]
not sections, but handbooks
The idea was with this restructuring was not to see the individual books as "sections," but rather as different handbooks with different purposes.
That being said, I'm more concerned about the usability problems for those that don't realize there are other handbooks; regular users will quickly become familiar with the new structuring. Suppose a newbie jumps into a handbook from an external link, rather than arriving there from the main handbooks listing page. We've added a "view other handbooks" to the quick links block, but I'm wondering if this will be enough?
My experience today
...is that the information is rather balkanized. Things that I consider customization are under development, for example. Without a cross-reference system, what if a taxonomy were initiated just for the handbooks? Or "see also" -type links?
For example, php snippets are scattered all over, yet I would consider them all closely related (code for blocks, code for pages, etc.). Terms such as "php code" "CSS" "database" etc. might help us jump across to what we're looking for. As it was, today I just gave up and went to my own bookmarks of forum discussions that had links to the handbook nodes. (It would be really nice if we had something like trip_search on Drupal.org.)
===
Laura
pingV
_____ ____ ___ __ _ _
Laura Scott :: design » blog » tweet
handbooks, yes
I would like to point out that I wrote the post from an unbiased point of view. I wrote my feelings when I browsed the handbook. You can see them as a useability test. So I am not poiting out what I would like to see changed, and then discuss that. I am pointing out what my first experience was. Use it, or ignore it ;)
Oh, and please change BOTH the tab and the aliased url into handbookS
---
if you dont like the choices being made for you, you should start making your own.
---
[Bèr Kessels | Drupal services www.webschuur.com]
pdf in drupal
I think it would be great if automatic-pdf producing of each node (also blogs and articles) would be possible generally in drupal.
The modules they are for download at the moment have the problem, that gif-images not be accepted, but many websites use gif-images and if the site is very large it is not very simple to change all the gifs to jpg or png.
I hope that there will be a solution for in future.
Respect to your Work here!
greetings from germany, holger
http://www.ebec.net . . .
http://www.stnetwork.de . . .