Gentoo Bug 42823 - Separate architecture-specific instructions dynamically

Description:

Opened: 2004-02-24 16:26 0000

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...

------- Comment #3 From je_fro 2004-03-14 17:18:25 0000 -------

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,

------- Comment #5 From Aaron Peterson 2004-03-15 13:31:15 0000 -------

>>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

------- Comment #6 From Xavier Neys 2004-03-15 13:58:02 0000 -------

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.

------- Comment #8 From Aaron Peterson 2004-03-28 17:27:57 0000 -------

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.

Bug 42823 depends on:			Show dependency tree
Bug 42823 blocks:			Show dependency tree

Bugzilla Bug 42823

Separate architecture-specific instructions dynamically

Last modified: 2004-04-02 05:27:51 0000