On my last install I used the Handbook version of the installation guide. Very good, very thorough - kudos to the authors. I do have one comment: A link needs to be added so users can get it on one page for printing. I see that the PDF version is in the works, but I've seen other sites with a similar doc style (click 'next' for next chapter, etc.) provide a link for getting the entiire doc in one web page. For something as complicated as a Gentoo install where there is still a lot the user has to do to get it installed, this is a must for offline reading and for use during the install itself. Providing this might also get rid of the need of having a PDF version too (and any overhead in maintenance if it's not auto-generated on the fly). Reproducible: Always Steps to Reproduce: 1. No steps, general comment on format/availability of printable version of docs. 2. 3. Actual Results: No single page, html printable version of install handbook available. Expected Results: Provide a link to give the entire install handbook in one html page, ready for printing.
Our current xslt implementation makes this a bit difficult, so you have to excuse me if I say that providing a PDF version has a higher priority (unless someone wants to take on the xslt transformation job to provide such a one-page version). The main difficulties are: - change in layout (as a one-page document requires four subdivisions instead of our current two subdivisions we provide - change in navigation (transformation from multi-page navigation to single-page navigation) - avoid duplication of remaining layout (our current implementation uses a cascade method which isn't possible for a single-page version) I'm going to set this as depending on the PDF version. If we can't make an online PDF document with the demands posed (up to date, automatic creation, professional layout) this will be the "failover" solution.
I'm going to attach the current handbook2pdf.xsl file to this bug. It is far from functional yet (I would say about 40%) and already demonstrates the existing issues. The main issue is that it graphically is less than good: the resulting PDF looks ugly imho. Other issues are nested commands, linking, table sizes and graphics. I will see if I can easily provide a one-page version for printing pleasure. It is easy, but it might be not that easy without changing a lot of internal coding to our stylesheets.
Created attachment 23182 [details] handbook2pdf.xsl
BTW, what's so difficult with printing the handbook chapter per chapter? It's not like we have hundreds of chapters... I've created a PDF of the handbook through mozilla (printing to ps and converting to PDF) which you can download from http://dev.gentoo.org/~swift/handbook.pdf. It's little over 1 Mb and covers both parts of the handbook. It's made for printing pleasure, not online (i.e. no links or anything that work, just like it was printed out).
I understand that there aren't a lot of chapters to print - for this particular doc. That's what I ended up doing. But then you end up with the same header info at the top all the time, and wasted white space at the end of a chapter. Providing a single page format ready for printing is much more user friendly, and if the sidebar stuff is dropped (just for the printable version) then it become even more compact for printing. And if the handbook format is the way the docs are going, then before development gets too far it's probably better to provide this capability now rather than trying to retro fit it later.
Ah, then you don't know of the &style=printable stuff :) If you add this to the URL of the handbook, the chapter you are viewing is rendered "printable" (without the bar on the right). For instance: http://www.gentoo.org/doc/en/handbook/handbook.xml?part=1&chap=5 becomes http://www.gentoo.org/doc/en/handbook/handbook.xml?part=1&chap=5&style=printable We aren't going to transfer all guides into the handbook, far from it. The reason the handbook exists is to have all Gentoo-specific items in one document: - Installing Gentoo - Working with Gentoo - Gentoo Desktop Configuration - Developing for Gentoo (At this point no other parts are queued) All other documentation (which is the documentation that is also interesting for non-Gentoo users) should remain in separate guides. Note that I fully understand your concerns; if I am able to have all chapters of a specific part in one page without too much hassle I will enable that functionality. I just need to do some research on it first...
Thanks for the tip on the &style=printable. That suits my needs (and probably others) nicely. As a reasonable compromise could a link be provided that uses this property? Most users (like me) may not know about the style property. Then at the bottom where you link to the next chapter, either pass the property along (assume if they went printable with one that's how they want them all), or provide two links, one going to the 'normal' version, the other going to the 'printable' version, that way the user can choose. This way you won't have to worry about combining it all into one page, but the users get the benefit of the more printer friendly format. With a side benefit of only having to print one specific chapter if that's all they want (which I could see being beneficial if one chapter gets updated rather than printing the whole thing OR guessing page ranges). Thanks again!
You can't default to a printable version when navigating because there is no navigation bar on printable versions, and I see no reason to put one. IMHO, it would be neater (and quite easy to do) to have an extra link in the current navigation bar to the printable version of the currently displayed page.
Going once, going twice, sold !! I'm gonna implement this right away...
I like winning auctions with no cost ;-) Anyhow, the link I was refering to was the one at the complete bottom of the page. I just checked, and not all chapters have a link to move to the next chapter. Providing the capability under the navigation bar makes sense, and is a clean solution. Kudos!
Done. Give it 59 minutes (at most) to propagate to the webservers. I'll mark this one as FIXED then (whoehoew :)
Yes, I'll see what chapters don't have a link and add it too.
