Gentoo Forums
Gentoo Forums
Gentoo Forums
Quick Search: in
Critical handbook bug!!! needs urgent fix!!!11
View unanswered posts
View posts from last 24 hours

 
Reply to topic    Gentoo Forums Forum Index Installing Gentoo
View previous topic :: View next topic  
Author Message
aoeuaoue
n00b
n00b


Joined: 26 Feb 2010
Posts: 31

PostPosted: Thu May 26, 2011 12:28 pm    Post subject: Critical handbook bug!!! needs urgent fix!!!11 Reply with quote

hello all,

First off I don't wanna sound like a whinner or a pricky nuisance but the handbook has a major flaw currently. Actually two. I was installing Gentoo when I came across the first bug on this section:

8. Configuring your System

Quote:
Code Listing 2.8: Adding net.eth0 to the default runlevel

# rc-update add net.eth0 default

If you have several network interfaces, you need to create the appropriate net.eth1, net.eth2 etc. initscripts for those. You can use ln to do this:

Code Listing 2.9: Creating extra initscripts

# cd /etc/init.d
# ln -s net.lo net.eth1
# rc-update add net.eth1 default



What's wrong with the above section? It tells to add something to the default run-level without actually creating it. My installation DID NOT have /etc/init.d/net.eth0 nor was automatically symlinked to /etc/init.d/net.lo. The second mistake is that it only mentions creating a second interface ln -s net.lo net.eth1 without the first. I would correct the above section as follows:
Quote:
Code Listing 2.8: Creating net.eth0 and adding it to the default runlevel

# cd /etc/init.d
# ln -s net.lo net.eth0

# rc-update add net.eth0 default

If you have several network interfaces, you need to create the appropriate net.eth1, net.eth2 etc. initscripts for those. You can use ln to do this:

Code Listing 2.9: Creating extra initscripts

# cd /etc/init.d
# ln -s net.lo net.eth1
# rc-update add net.eth1 default


This bug could actually explain the hordes of n00bs spamming #gentoo about their network interface not being brought up upon boot.

The next handbook bug is even more alarming, from the same section:

8. Configuring your System
Quote:
Gentoo uses /etc/conf.d/clock to set clock options. Edit it according to your needs.

What? The file /etc/conf.d/clock neither its /etc/init.d/clock are currently used by Gentoo as I found out through un-official sources. The correct file is in /etc/conf.d/hwclock which has its corresponding /etc/init.d/hwclock. Next the section gives a description how to do it:

Quote:
Code Listing 3.4: Opening /etc/conf.d/clock

# nano -w /etc/conf.d/clock

If your hardware clock is not using UTC, you need to add CLOCK="local" to the file. Otherwise you will notice some clock skew.

You should define the timezone that you previously copied to /etc/localtime so that further upgrades of the sys-libs/timezone-data package can update /etc/localtime automatically. For instance, if you used the GMT timezone, you would add TIMEZONE="GMT"

When you're finished configuring /etc/conf.d/clock, save and exit.


So here the entire section is incorrect because /etc/conf.d/clock doesn't exist!! Currently Gentoo uses /etc/conf.d/hwclock in which case an updated version would read as follows:

Quote:

Gentoo uses /etc/conf.d/hwclock to set clock options. Edit it according to your needs.

Code Listing 3.4: Opening /etc/conf.d/hwclock

# nano -w /etc/conf.d/hwclock

If your hardware clock is not using UTC, you need to add CLOCK="local" to the file. Otherwise you will notice some clock skew.

You should define the timezone that you previously copied to /etc/localtime so that further upgrades of the sys-libs/timezone-data package can update /etc/localtime automatically. For instance, if you used the GMT timezone, you would add TIMEZONE="GMT"

When you're finished configuring /etc/conf.d/hwclock, save and exit.


In addition in this section would be a good idea to explain "If your hardware clock is not using UTC, you need to add CLOCK="local" to the file. Otherwise you will notice some clock skew. " Which kind of hardware would NOT use UTC? Why would a hardware NOT use UTC? How would some be able to tell whether their hardware use UTC or something else?? So the difference between "UTC" and using "local" isn't entirely clear.

The Gentoo handbook has an update timestamp off "Updated May 9, 2011" which is full 20 days without being fixed, and certainly ever since the the switch from /etc/conf.d/clock to /etc/conf.d/hwclock. And who knows how long it has been. However the handbook got 35 editors I am positive the two bugs can be fixed in a pronto fashion. I'll give it maximum 2 hours from this post until my next refresh of Gentoo handbook page.

Please don't think I am beeotching or anything, just trying to keep a first class meta-distro with a first class, error-free, handbook :D

Thanks in advanced!!

edit: updated the clock section.


Last edited by aoeuaoue on Thu May 26, 2011 6:17 pm; edited 3 times in total
Back to top
View user's profile Send private message
tomk
Administrator
Administrator


Joined: 23 Sep 2003
Posts: 7219
Location: Sat in front of my computer

PostPosted: Thu May 26, 2011 1:14 pm    Post subject: Reply with quote

You should report bugs on bugzilla.

I'm also not sure what MW3 has to do with anything?
_________________
Search | Read | Answer | Report | Strip
Back to top
View user's profile Send private message
Takkun
n00b
n00b


Joined: 07 May 2011
Posts: 15

PostPosted: Thu May 26, 2011 1:47 pm    Post subject: Reply with quote

I'll assume you hit both of these after the baselayout update and openrc.

If so, both these are addressed in the migration guide, net.eth0 can sometimes disappear in the update, and /etc/conf.d/clock has been replaced with /etc/conf.d/hwclock. I'd be surprised to see settings being placed in /etc/init.d/

The reason behind the stage3 not including baselayout2 is due to a couple(?) show stopping bugs, hence the roll back to baselayout1 stage, and removal of the baselayout2 stages. This will get fixed in due time, and I'm sure the installation guide will get updated to suit.

[ninja-edit]

Should probably point out, I believe the bugs related to baselayout2 in the stages is to do with the autobuild system, not the actual baselayout
Back to top
View user's profile Send private message
aoeuaoue
n00b
n00b


Joined: 26 Feb 2010
Posts: 31

PostPosted: Thu May 26, 2011 2:20 pm    Post subject: Edit Reply with quote

First off sorry for Modern Warfare 3 youtube link earlier, it was in the buffer of my shift+insert. Somehow right click on a link in FF and copy the link doesn't get overwritten with regular text highlighting. The thing is that I pressed the 'submit' button instead of preview at the very beginning of writing this entry.

@tomk

How would I submit that to bugzilla? Is not an ebuild, there's no source where I can use diff and submit the resulting handbook.patch, that's why I came here. The other option is to email this post to every contact in the handbook page.

@Takkun

Nope, mint install with stock minimal LiveCD and stage3, didn't even get to install any extra package. In other words, whatever is there is from stage3. Also why should someone following the handbook have to look to the migration guide? A link in the in the handbook would be a workaround but that's besides the point though.
Back to top
View user's profile Send private message
John R. Graham
Administrator
Administrator


Joined: 08 Mar 2005
Posts: 7806
Location: Somewhere over Atlanta, Georgia

PostPosted: Thu May 26, 2011 2:29 pm    Post subject: Re: Edit Reply with quote

aoeuaoue wrote:
How would I submit that to bugzilla? Is not an ebuild, there's no source where I can use diff and submit the resulting handbook.patch, that's why I came here. The other option is to email this post to every contact in the handbook page.
Documentation is one of the bug categories listed on the very first page of the new bug creation dialog. It even explicitly mentions the Handbook. You've got a good description here; just use it as the text of the bug.

- John
_________________
This space intentionally left blank.
Back to top
View user's profile Send private message
tomk
Administrator
Administrator


Joined: 23 Sep 2003
Posts: 7219
Location: Sat in front of my computer

PostPosted: Thu May 26, 2011 2:40 pm    Post subject: Re: Edit Reply with quote

aoeuaoue wrote:
First off sorry for Modern Warfare 3 youtube link earlier, it was in the buffer of my shift+insert. Somehow right click on a link in FF and copy the link doesn't get overwritten with regular text highlighting. The thing is that I pressed the 'submit' button instead of preview at the very beginning of writing this entry.

I thought it must be something like that.

I didn't realise it was baselayout2 related, in which case you should have a look at this topic: Install guides need updating.

aoeuaoue wrote:
How would I submit that to bugzilla? Is not an ebuild, there's no source where I can use diff and submit the resulting handbook.patch, that's why I came here. The other option is to email this post to every contact in the handbook page.

You can submit bugs against documentation. Choose the product 'Documentation' and component 'Installation Handbook'. If you want to supply a diff you can get the XML source for any Gentoo documentation by adding &passthru=1 to the URL, although this requires some knowledge of the GuideXML syntax used.
_________________
Search | Read | Answer | Report | Strip
Back to top
View user's profile Send private message
krinn
Advocate
Advocate


Joined: 02 May 2003
Posts: 4280

PostPosted: Thu May 26, 2011 4:38 pm    Post subject: Reply with quote

aoeuaoue wrote:
This bug could actually explain the hordes of n00bs spamming #gentoo about their network interface not being brought up upon boot.


No, this explain hordes of users not reading or understanding the upgrade guide. It has nothing to do with been a new user on gentoo.

I really don't like that "noobs" word and as you've made errors at fixing the doc, i'm pretty sure you didn't read it too, so you may just be in the same category you've put them in.
Back to top
View user's profile Send private message
kwilliams0
n00b
n00b


Joined: 26 May 2011
Posts: 21

PostPosted: Thu May 26, 2011 5:35 pm    Post subject: Reply with quote

Did you log this?

I thought the same when I did my install (had to go through it a few times, and later saw the way to check if it would be loaded, saw it wasn't, and then added the link to force it). Also took me a bit to realize it is hwclock and not clock (and I didn't think it's hwclock so maybe I should not have used local there...now I'm confused :( ).

If you didn't log it, I will. I want to do my part and contribute. I brag constantly about Gentoo being the best distro to really learn how linux works, with the best documentation.
Back to top
View user's profile Send private message
aoeuaoue
n00b
n00b


Joined: 26 Feb 2010
Posts: 31

PostPosted: Thu May 26, 2011 7:18 pm    Post subject: bugzilla filed!! Reply with quote

alright,

@kwilliams0

I filed a bugzilla --> http://bugs.gentoo.org/show_bug.cgi?id=368793


@krinn

I don't know how to address your reply, really. The term 'hordes of n00bs' is meant to emphasize how many instances this glaring ERROR unnecessarily trips first timers and strain #gentoo support by something that can be easily avoided by the corrections that I provide. Also you condemn me, erroneously, of condemning n00bs while yourself insulting the intelligence of n00bs (quote "users not reading or understanding the upgrade guide") and faulting them from being careless readers and not RTFM, when IT'S NOT THEIR FAULT, that the handbook has a mistake. That's some hypocrisy right there.

And yes I am not, by any stretch of the imagination, an expert and so far the only error in the correction was not including the updated "Gentoo uses /etc/conf.d/hwclock to set clock options. Edit it according to your needs." I cannot help but laugh when you say I am not reading the doc, the error is clearly there, either I have a really bad sight or you are high on some Mexican mescaline (optical distortion, fractal vision). Given you are registered 2003 I would've expected some constructive feedback instead of an unhelpful and illogical drivel.

Anyways, I only want a quality handbook that reflects the updated files and doesn't fall into mediocrity.
Back to top
View user's profile Send private message
NeddySeagoon
Administrator
Administrator


Joined: 05 Jul 2003
Posts: 32027
Location: 56N 3W

PostPosted: Thu May 26, 2011 8:16 pm    Post subject: Reply with quote

aoeuaoue,

The handbook is correct, the Gentoo provided stage3, containing baselaout2 is broken
The leaves new installs having to start with baselayout1 and getting baselayout2 with the only warning being the news item, which most new users will skip in their excitement.

Gentoo is temporaraly stuck in the transition between baselayout1 and baselayout2 because the baselayout stage3 is broken.
When its fixed, the handbook will be switched to cover a baselaout2 install. Either way the /etc/conf.d/net.eth0 will be provided in the stage3.
_________________
Regards,

NeddySeagoon

Computer users fall into two groups:-
those that do backups
those that have never had a hard drive fail.
Back to top
View user's profile Send private message
krinn
Advocate
Advocate


Joined: 02 May 2003
Posts: 4280

PostPosted: Thu May 26, 2011 8:21 pm    Post subject: Reply with quote

I'm not condeming users intelligence like you are saying by using the "nOObs" word like you're doing.
Not even by saying users cannot understand the doc, not everyone speak the language the doc was written. That's just a lack of knowledge, not a proof of stupidity.
Users not reading doc is also not a proof of stupidity, maybe a proof of lazzyness.

In fact, i've just show you, that you shouldn't use that word, as its usage is insulting others, and your answer proof you know it's not a word to call someone by.
That's just what i was telling you, and you didn't really get it as "while yourself insulting the intelligence of n00bs" shown.

If users can't have the doc, it's not their fault right, i agree with that, see, i even try to make that change : http://bugs.gentoo.org/show_bug.cgi?id=367067

But for the baselayout2 it's not the case, it has been running for years in testing, and the doc has been made and pretty well announce :
- the doc: http://www.gentoo.org/doc/en/openrc-migration.xml
- the forum announce : http://forums.gentoo.org/viewtopic-t-877439.html
- the webpage announce : http://www.gentoo.org/news/20110505-openrc.xml
And people already told you it's baselayout issue and it was rollback to baselayout1 on install : so the install doc remain good until install will be baseyout2.

And if you read it, you will notice that: http://forums.gentoo.org/viewtopic-p-6688597-highlight-hwclock.html#6688597

While you're at it, maybe modify your corrections to include the fact timezone section is bad no ?
And, maybe, why not, drop the noob term also ? As it seems it upset you so much that you feel the need to say i might use drugs.
Back to top
View user's profile Send private message
NeddySeagoon
Administrator
Administrator


Joined: 05 Jul 2003
Posts: 32027
Location: 56N 3W

PostPosted: Thu May 26, 2011 9:04 pm    Post subject: Reply with quote

This thread is not in OTW ... yet.

Please stick to technical discussion related to the topic.
_________________
Regards,

NeddySeagoon

Computer users fall into two groups:-
those that do backups
those that have never had a hard drive fail.
Back to top
View user's profile Send private message
polslinux
Apprentice
Apprentice


Joined: 12 Apr 2010
Posts: 251
Location: Veneto

PostPosted: Thu Aug 25, 2011 6:14 pm    Post subject: Reply with quote

also udev, upower, udisks and hal"sectomy" aren't into the handbook!
_________________
PC-Desktop: Ubuntu 12.04 x86
Notebook Sony Vaio VPCEH: Gentoo ~amd64
Back to top
View user's profile Send private message
Display posts from previous:   
Reply to topic    Gentoo Forums Forum Index Installing Gentoo All times are GMT
Page 1 of 1

 
Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum