I find it difficult to navigate the gentoo handbook's install guide. There is a fairly easy way to make the architecture specific instructions go away temporarily, while maintaining the current format on older browsers and for those who wish to have it as it is. All this requires is an arch_specific="x86" tag wrapping the architecture specific areas, and then I'd be happy because I could implement the rest by editing the css... but the next logical step is to use the css hidden feature <arch_specific="x86"> choose your cpu </> <arch_specific="sparc"> choose 64bit blah if blah </> psudo css: css { arch_specific: style =normal ) { arch_specific=x86 style =normal) or whatever, and then have javascript change the css to style="hidden" For more information, look up css, and css menus css drop down menu's show how to hide elements based on the mouseOver event... we would have a form element with checkboxes that implements a hide_arch() function Reproducible: Always Steps to Reproduce: 1. 2. 3. If interest is expressed, I am willing to develop a prototype... It seems like it would be very simple to implement, and even if the java script stuff doesn't work, I would use my browsers css editing feature to hide the unwanted information overload Marked as Normal even though it is an enhansement because I find it difficult to use the handbook...
The solution (if any) should really be a bit more generic, allowing for the links/lynx users to be able to hide the architecture-specific instructions too. Please join gentoo-doc@gentoo.org (gentoo-doc-subscribe@gentoo.org) and contribute to the current ongoing discussion: http://news.gmane.org/gmane.linux.gentoo.documentation, thread "Separating architecture-specific instructions from Handbook"
The requirements: http://article.gmane.org/gmane.linux.gentoo.documentation/1055
I've relied on the Installation Documentation for x86 and sparc for a long time. I seethat the Handbook has replaced all those installation guides that I've _relied_ on for so long. IMHO, the Handbook is not yet suited for most folks looking to install gentoo. Worse, it is difficult to find arch specific stuff. I realize you guys have hard, thankless jobs but could you _please_ put the table with the Install Guides (for various architectures) back on gentoo.org? Especially the one for sparc? Thank You,
I feel the handbook *is* suitable for installing Gentoo, regardless of architecture. I am not going to reinstate the old guides, sorry.
>>It's hard to find [stuff] >I am not going to reinstate the old guides, sorry. I think what je_fro is asking for, is just to make the old versions of the install guides available... I don't think he's asking for more development on them. I know I was up a creek without a paddle when the documentation changed, and I had an old implementation of a feature, and had to go find the new documentation, and figure out what had changed. Having the old versions around (or instructions for receiving the old versions from CVS) would be very usefull. I know that I stopped using the handbook because I spend so much time scrolling around, missing steps and all. When my gentoo goes unstable, I have been forced to use something else untill it annoys me enough to search through the documentation. also, the GWN could show a list of packages that are scheduled to change implementation / functionality, so we can be prepaired to change them rather than googling for it when it breaks
Old docs are still available in our CVS at http://www.gentoo.org/cgi-bin/viewcvs.cgi/en/?root=doc In particular, the latest Sparc install guide can be found at http://www.gentoo.org/cgi-bin/viewcvs.cgi/en/gentoo-sparc-install.xml?rev=1.28&root=doc&content-type=text/vnd.viewcvs-markup As a one-off goodwill gesture, I give you a rendered html version at http://dev.gentoo.org/~neysx/tests/gentoo-sparc-install.html Use it while it lasts, I'll leave it there only for a few days. Don't ask for other docs, this was a one-off gesture. Read http://www.gentoo.org/doc/en/doc-tipsntricks.xml?style=printable to learn how to render our xml docs yourself.
Futher update: http://article.gmane.org/gmane.linux.gentoo.documentation/1178
I agree that "dynamic" separation of the documentation is not enough. If we are going to continue growing, we need to have the documentation be updated by the people who change the functionality... and the dynamic hiding of arch specific information won't solve that problem. I think we should have a database (basically a wiki), with each page being a paragraph, or even sentence!.. or any arbitrarily small content difference... and have the page be glued together. With this system, we could write once, use many, have architecture specific guides be generated, have all inclusive guides be generated, and have the ower of certain packages be responsible for product documentation. we have no need to rewrite the architecture independent portions of the guide for each architecture, we do need to hide extraneous information... Database table: Table_of_Pages page_name page_title page_url page_id page_content (page content can included references to other pages that include other pages) note, page categories could become a class of page_architecture (decide if coma separated or an entry for each architecture, and or have a keyword all.) or page_arch_i36 w/ page_arch_alpha w/ page_arch_ppc w/ page_arch_sparc w/ page_arch_all w/ page_arch_little_endian w/ page_arch_big_endian (a group of all architecures that are this way) w/ page_arch_other_group_of_arches document_categorory_to_document_id Category_name category_id category_document_id this list is not one to one... some troubles arise if there is more than one category to a page note, each page has a content area.. that may contain inclusions of a category or specific page, which includes it's contents... risk of infinite recursion is possible, but should be stoped at 5 layers or less... Category_Product page_id team_category_id (the Category_Architecture page_id architecture_category_id or we could have a category page for each specific archtecture... I'm not a database designer. Each maintainer of whatever program is responsible for vis own section. The content would be in your docbook format, and would be embeded in a container document that has the appropriate headers and footers.. and the content would have some form of markup to denote inclusion of other pages. http://wiki.linuxquestions.org uses the wikipedia engine, which has a sort of method to modify only specific sections of a wiki page... this is similar to what i am thinking about, and it may have the functionality already there... but I haven't seen it... I am very much wanting to make this system... er... have a system like this available. Superman could not keep up with the daily changes of the system. We need a team tool, and we need the people familiar with the architecture to write the actual instructions on how to do things, editors can come and make it pretty.. but pretty doesn't matter, functionality and navagatabilty are important, and having the page full of irrelevant info is contrary to navagability.
Using wiki-style approach has its advantages, but it's not the end-of-all-for-you-all tool as it has disadvantages as well. Anyway, please keep this bugreport on topic - discussions should be held on the gentoo-doc mailinglist (or in a separate, on-topic bugreport).
*** Bug 46431 has been marked as a duplicate of this bug. ***
Drafts: http://www.gentoo.org/doc/en/handbook/draft/handbook-x86.xml http://www.gentoo.org/doc/en/handbook/draft/handbook-alpha.xml http://www.gentoo.org/doc/en/handbook/draft/handbook-sparc.xml http://www.gentoo.org/doc/en/handbook/draft/handbook-hppa.xml http://www.gentoo.org/doc/en/handbook/draft/handbook-ppc.xml http://www.gentoo.org/doc/en/handbook/draft/handbook-mips.xml http://www.gentoo.org/doc/en/handbook/draft/handbook-amd64.xml
Fixed in CVS.
thanks! the betas looked cool.
