Hi all,

I'm not happy to mail this as I'm against it, but #gentoo-dev was really in
favor of this, so here it goes.

The idea is to separate the architecture-specific instructions for the user
so that they are able to print out the installation instructions for their
architecture only. This should probably be done dynamically (so user selects
his architecture in the beginning).

The whole discussion is (very long):

09:38 <@seemant> SwifT: apparently, people are finding it hard to read the 
                 multi-arch full instruction set -- is there a way to 
                 dynamically generate individual arches' docs from the main 
                 (just for online browsing, NOT downloading)
09:38 <@seemant> SwifT:  can mail you a reminder, but wanted to talk realtime 
                 first
09:39 <@SwifT> seemant: everything is possible, but that idea has been 
               discussed previously and not accepted because it requires 
               several updates on how the handbook is written. 
09:39 <@seemant> oh?
09:39 <@SwifT> seemant: see www.gentoo.org/doc/en/handbook, it's a FAQ
09:40 <@SwifT> http://www.gentoo.org/doc/en/handbook/index.xml#doc_chap4_sect2 
               to be precise
09:41 <@seemant> SwifT: yeah, that pertains to the different choices, which I 
                 agree would be a nightmare
09:41 -!- alice_ [~alice <at> ppp-62-245-208-224.mnet-online.de] has joined 
          #gentoo-dev
09:41 <@seemant> SwifT: I'm more referring to the different architectures 
                 (which, after the intial choice of arch, is never again an 
                 issue)
09:41 <@seemant> like x86 specific, sparc specific, ppc specific
09:41 <@SwifT> maintenance would still be a pita
09:41 <@seemant> etc and so on
09:42 <@seemant> it would?
09:42 -!- hattya [~hattya <at> ntsitm091171.sitm.nt.ftth.ppp.infoweb.ne.jp] has 
          joined #gentoo-dev
09:42 -!- mode/#gentoo-dev [+o hattya] by ChanServ
09:42 <@seemant> presently, each arch maintainer mails you their specific 
                 changes/needs to be added in, no?
09:42 <@dams> morning
09:42 <@dams> seemant: got time to look at the ebuild?
09:42 <@SwifT> seemant: presently I have to ask arch maintainers why I receive 
               bugreports from users instead of mails from arch maintainers :p
09:43 <@seemant> dams: wow, I totally forgot :/
09:43 <@dams> :)
09:43 <@seemant> dams: I'm SOOOOOOOOOOOOO sorry
09:43 <@dams> no problem
09:43 <@Peit|Home> SwifT: perhaps because the users know that you're the doc 
                   lead,
09:43 -!- Livewire [rlj2 <at> dialup-67.29.205.192.Dial1.Cincinnati1.Level3.net] has 
          quit [Read error: 110 (Connection timed out)]
09:43 -!- Livewire [rlj2 <at> dialup-171.75.110.13.Dial1.Cincinnati1.Level3.net] has 
          joined #gentoo-dev
09:43 <@`Kumba> I think instead of dyanmically generating, default to showing 
                x86 instructions, and allow a dropbox to select other arch 
                instructions
09:43 <@dams> I can ask some -ppc guy if they have time
09:43 <@Peit|Home> SwifT: and perhaps the maintener wasname(attribute) for each 
                   part of the doc isn't highlighted enough to make it a 
                   no-brainer
09:44 <@SwifT> :)
09:44  * Peit|Home debates between heading off to work, or rsyncing 9gig of data
09:44 <@SwifT> I just don't see why the doc-team has to put so much effort in 
               creating a dynamical version for the few architecture-specific 
               parts; I would propose to see how we can rewrite those parts so 
               that users are less frightened
09:45 <@SpanKY> just hook into herd.xml to extract arh leads :p
09:45 <@SpanKY> SwifT: because as we add archs, we add docs
09:45 <@SpanKY> and as we add docs, the docs get bigger
09:45 <@Peit|Home> SwifT: because it's our job :P (insert as many similies as 
                   you feel free)
09:45 <@SwifT> ;)
09:45 <@SpanKY> why print pages of stuff related to hppa/ppc/sparc when all you 
                want is x86
09:45 <@SwifT> it's my job to write documentation, and currently the amount of 
               written documentation is at a depth
09:46 <@Peit|Home> SwifT: perhaps you need a doc-infra type person
09:46 <@`Kumba> Swift: dyanmically generating is probably overkill, but 
                presenting all the arch instructions on one page is information 
                overload I think.
09:46 -!- spyderous [~spyderous <at> sfa232052.richmond.edu] has quit ["Client 
          exiting"]
09:46 <@Peit|Home> SwifT: someone to do the arrangement of the docs you write
09:46 <@jstubbs> SwifT: before i forget again, the link to the handbook on the 
                 main page is called "Gentoo Handbook Installation 
                 Instructions". Now that the handbook covers more than 
                 installation, perhaps that should be split into two? Many who 
                 are aware of the handbook aren't aware of more than the first 
                 section.
09:47 <@SwifT> perhaps we should investigate how to fold sections/chapters
09:47 <@SwifT> although that would probably hit lynx/links users with some 
               furious anger
09:47 <@SwifT> jstubbs: well, the other part isn't "Installation" related :)
09:47 <+mcf> SwifT, hum, yeah the install handbook is already hard enough to 
             read in links ;|
09:47 <@Peit|Home> SwifT: hmm, we should be able to do it dynamicall, apache 
                   and axkit will handle the caching of the "generated" pages
09:47 <@`Kumba> Swift: what about my drop-box idea, to select a different arch 
                and re-load that page with those arch instructions (calling 
                say, a separate xml file)?
09:48 <@`Kumba> that should keep lynx compatibility
09:48 <@SwifT> `Kumba: if you're volunteering, be my guest :)
09:48 <@Peit|Home> `Kumba: i like it (but that's because i also thought of it, 
                   but didn't say anything)
09:48 -!- spyderous [~spyderous <at> sfa232052.richmond.edu] has joined #gentoo-dev
09:48 -!- mode/#gentoo-dev [+o spyderous] by ChanServ
09:48  * `Kumba just volunteers ideas... :)
09:48 <@SwifT> currently the doc is written with the idea that all 
               architectures are viewable, so it'll read some redesign
09:48 <@SwifT> s/read/need/
09:48 <+mcf> Is there a text-only version of the handbook ? I didn't see one on 
             the 0204 livecd
09:48 <@seemant> SwifT: btw, the dynamic generation issue, isn't really dynamic 
                 "generation" it's just grep -v'ing (effectively) all the 
                 non-${MY_ARCH} related stuff
09:49 <@seemant> mcf: there will be on the final one
09:49 <@SwifT> seemant: but there are several hints and paragraphs on 
               architecture-choices that cannot be easily dismissed; they need 
               to be rewritten
09:49 <@seemant> SwifT: par example?
09:49 <+mcf> seemant, k.
09:50 <@SwifT> seemant: 
http://www.gentoo.org/doc/en/handbook/draft/handbook.xml?part=1&chap=2#doc_chap1_sect2
09:50 <@SwifT> seemant: actually the whole page :p
09:50 -!- tberman [~Todd <at> tberman.registered.freenode] has quit [Connection 
          timed out]
09:51 <@SwifT> the overviews on the supported archs, livecds, ...
09:51 <@seemant> yeah, I see what you mean
09:51  * `Kumba might try the select-an-arch issue for the old mips guide to 
          switch between SGI & cobalt instructions once he writes them
09:51 <@SwifT> and separating those instructions in architecture-specific 
               chapters (making some duplicate efforts) would go against my 
               idea on integrating the architectures
09:52 <@SwifT> I'd rather have the architectures mainstream their development 
               so that the installations are almost architecture-independent
09:52 <@SwifT> catalyst is a real good start
09:52 <@nerdboy> night ppl
09:52 -!- nerdboy is now known as nerdboy|off
09:52 <@Peit|Home> SwifT: it's a lovely idea, but pretty much all archs other 
                   than x86 have unique initial boot requirements
09:53 <@seemant> SwifT: for the most part they do seem to be mainstreamed, 
                 except for things like bootloaders
09:53 <@Peit|Home> SwifT: but it's only that boot that i'm aware of being the 
                   main difference
09:53 <@`Kumba> Swift: bit difficult, as archs have their respective variations 
                in things like fdisk, the bootloader, post installation 
                instructions, etc..
09:53 <@Peit|Home> SwifT: everything else is standard,..
09:53 <@seemant> yeah @ fdisk, I forgot about that
09:53 <@SwifT> Peit|Home: booting the medium, bootloader installation and 
               partitioning
09:54 <@Peit|Home> perhaps we need to devide it, "prepare the system" and 
                   "installing the system"
09:54 <@Peit|Home> preparation being boot, hd prep
09:54 <@Peit|Home> installing being everything else
09:54 -!- bcowan [~bcowan <at> dsc01-dav-oh-207-95-173-32.rasserver.net] has quit 
          [No route to host]
09:54 <@spyderous> you ought to be able to click a link right at the beginning 
                   for your arch
09:54 <@spyderous> and that would autoformat the handbook
09:54 <@spyderous> drop all the arch-dependent sections that aren't your arch
09:54 <@SwifT> autoformat -> difficult for offline testing on docs-team
09:54 <@Peit|Home> only the bootloader (which comes later) is the other part
09:55 <@`Kumba> also, some archs have livecds, others have netboots, making the 
                initialization slightly different (and some archs can use 
                either livecd or netboot, depending on the type of machine)
09:55 <@SwifT> only a few of my members have axkit installs on their system
09:55 <@Peit|Home> swift autoformat=select <xml arch="hppa">
09:55 <@spyderous> SwifT: then set up a parallel online site on gentoo.org, in 
                   your webspace perhaps
09:55 <@spyderous> your = gdp
09:55 -!- alice [~alice <at> ppp-62-245-208-228.mnet-online.de] has quit [Client 
          Quit]
09:56 <@spyderous> would require some tweaks to locations of dtd etc, but not 
                   much
09:56 <@SwifT> I'm still against it, but i'll launch the idea on gentoo-doc
09:56 <@spyderous> i'm against people seeing a bunch of cruft they couldn't 
                   care less about
09:57 <@seemant> "customised views" is really what we're suggesting
09:57 <@seemant> like "masking off" certain bits of the handbook
09:57 <@spyderous> like 5 different ways to boot a ppc, when you're installing 
                   x86
09:57 <@spyderous> it's just confusing
09:57 <@SwifT> I just don't see it really beneficial as the install 
               instructions will grow anyway beyond the current length and 
               users will start asking for more masking (not only architecture, 
               but also choices)
09:58 <@seemant> SwifT: I'd draw the line at architectures, not choices
09:58 <@seemant> although I do see your point about slippery slopes
09:58  * Peit|Home can't see how much more basic we can get, (or are we talking 
          about integrating the desktop howto and friends)?
09:58 <@dams> btw guys, ruby rocks :) saw the presentation yesterday
09:58 <@seemant> but the difference we're talking about is "absolutely won't 
                 need on x86" vs. "possibly won't need on x86" (taking x86 as 
                 an example)

As always, feedback is appreciated.

Wkr,
	Sven Vermeulen

-- 
  FOSDEM 2004               Free and Open Source Developers European Meeting
  21 - 22 februari          Brussels, Belgium          http://www.fosdem.org

  http://www.gentoo.org     Documentation & PR              swift <at> gentoo.org