Hello ----------------------------------------------------------------- this is not a bug --just a suggestion--- but (if I understand wll) gentoo site encourages reporting different opinions on handbook on bugzilla! ---------------------------------------------------------------- Problems that I found reading and studing the handbook & some suggestions: 1) I believe that the handbook (and eventually other big documents of yours) should be improved and more structured in terms of sections, section numbering and print-out. For instance take section 5: I found 5 Installing the Gentoo Installation Files 5.a Installing a Stage Tarball -Setting the Date/Time Right -Making your Choice 5.b. Default: Using a Stage from the Internet -Downloading the Stage Tarball -Unpacking the Stage Tarball ..... Problem: the subsubsections (denoted here by -) are difficult to be identified because they are submerged by a lot of tables filled in the text. Moreover they are PRINTED OUT in a clear grey and small fonts that could lead to miss one of them. (please don't ask final users to tweak printer parameters!!!!) Proposed Solution: NUMBERS!!!! Example: 5 Installing the Gentoo Installation Files 5.1 Installing a Stage Tarball 5.1.1 Setting the Date/Time Right 5.1.2 Making your Choice 5.2 Default: Using a Stage from the Internet 5.2.1 Downloading the Stage Tarball 5.2.2 Unpacking the Stage Tarball .... Of Course the numbering system should be accompaigned with a better printing (appropriate fonts and textures) of sub-sub-section names referring to black an white printers (guess gentoo users are not so reach to print 50 pages in colours at each handbook upgrade) More in general I think that the handbook's most common use is to be printed and then read read and read again (I cannot figure out people reading 50 pages on a display): i.e. hand book is a BOOK! In this sense I feel that the xml presentation with nice colors and links is appropriate for advertising gentoo and for online viewing of small one page documents or parameters but not at all appropriate for big reference docs like the handbook. I think that it would be better to produce these documents directly in a more appropriate editorial environment like LaTeX (that automatically deals with numbering index and all of those items that are ESSENTIAL in a easily readable handbook) and then translated in ps or pdf. Of course the automatic translation Latex -> xml would take some effort and will not give such a nice results as direct xml writing but the goal -in my (final user)mind-- is a nice printable version of the handbook with indexes appendices and all that is required to structurating and speeding up the lecture. 2) Concerning the problem of system dependent branches according to the system.... whell it is difficult to follow all branches and options.... BUT the situation can be improved! Here is my suggestion: -I assume that you follow my previous suggestion, i.e. increse the depth of section numbering to sub sub sections.- then what you have to do is just to add at the beginning a list of some possible road maps in which the document can be read: eg. you want a stage 3 on a sparc with genkernel then follow sections: 1.2.3 [1.3.2] 2.2 2.3 [2.3.1] .......10.2.1 10.3 you want a stage 2 on a AMD 64 with your own kernel then follow sections: 1.2.3 [1.3.4] 2.5 2.7 2.9.1 .......10.2.3 10.3 where [...] are optional sections.... well that's all for the moment, I'll come later to see is someone will need some more details. Have a nice day, riccardo ps by the way thanks to all gentoo developers & hard workers!!! Reproducible: Always Steps to Reproduce: 1. 2. 3.
First of all, thanks for the feedback. I do appreciate it, even though you might think differently after reading this comment :) The first suggestion you made was to add numbering to the sections. This is a good suggestion, but I'll leave it as is for now due to the following reasons: 1. Adding numbers to the sections can only be done globally for the entire website (which requires some more bureaucratic stuff), except when messing with the stylesheets (which makes the code look more like an italian spaghetti-fest than real code) 2. Sections are generally quite small. Adding numbers isn't really necessary imho. 3. Having a 4-level deep numbering scheme (part.chapter.section.subsection) isn't adviseable layout-wise (it looks ugly to read "1.2.d.1 ARCH or not?") The second suggestion is regarding printing. The online docs are meant for online viewing. We provide them too in a printable format, but we are not able to change the output of this format more to your liking as it uses the same rendering code as the online viewing. The main reason for the printable version is to remove the tables and such. We will provide PDF versions of the Gentoo Handbook (see http://dev.gentoo.org/~plasmaroo/handbook-test) once our convert-to-pdf server is in place (it requires lots of CPU resources to create PDF versions everytime the Gentoo Handbook is altered - which is sometimes several times a day). This PDF is more suited for printing. We don't use LaTeX because we want to keep our GuideXML format for all documentation and website development. This keeps all efforts centralised. Knowing GuideXML is easier than knowing LaTeX (or DocBook or any other language for that matter) and we want to make it easy for people to write documentation. If you want you can create a GuideXML2LaTeX XSL transformation stylesheet. It's been done in the past for regular guides, so making this for the handbook shouldn't be that difficult. I wont place a "follow foo, bar, bleh, blabla, blut" reference in the documentation. It's plain ugly (excuse the language) and difficult to maintain. It would also encourage people to read the documentation diagonally even though they're not used to installing Gentoo, which makes the process more errorprone. For these reasons I'm marking this as WONTFIX. Once again, not because I would hate you or anything because you've reported it, but for the reasons above :)
