Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!

Bug 323381

Summary: Handbook Comments
Product: [OLD] Docs on Reporter: Kevin Grigorenko <kevin.grigorenko>
Component: Installation HandbookAssignee: nm (RETIRED) <nightmorph>
Severity: normal CC: docs-team
Priority: High    
Version: unspecified   
Hardware: AMD64   
OS: Linux   
Package list:
Runtime testing required: ---

Description Kevin Grigorenko 2010-06-10 00:44:24 UTC
Hello, I have a few comments on the handbook:

1. Given that the latest GCC is 4.3.x, shouldn't the recommendation be -march=native? Also, at minimum for the part that says "# EM64T users should use -march=nocona" should at least be -march=core2 instead as it's newer. Also, shouldn't the code listing be 5.x instead of 4.2? I noticed this because I wanted to give the below link with an anchor directly to that code listing, but there was another with the same anchor already.

2. 'Machine Check Exception' does not exist in my kernel, instead it was 'Machine Check / overheating reporting'.

Overall the handbook is great, Thank you.

Reproducible: Always

Steps to Reproduce:
1. Open the handbook
2. Open eyes (blinking every once in a while, as necessary)
3. Read the handbook
Comment 1 nm (RETIRED) gentoo-dev 2010-07-13 00:53:58 UTC
1. -march=native is much harder to implement, since we would need to make some extensive changes with how we program our handbooks.

However, I did update it to -march=core2, rather than the old P4-era nocona.

2. The code listing is correct; this is auto-generated from the part, chapter, and sections listed. We never put in numbers; our xml/xsl interpreter and webserver compute this automatically.

Try viewing it in the separate pages, rather than the all-in-one view, to see how parts, chapters, and sections are assigned.

The numbers in the big bold black text sections don't have any relation to the stuff beneath them. Those are considered chapters, and for each of those chapters, the numbers of code listings and whatnot beneath them are counted uniquely, starting over with each new chapter.

A better example of how chapters work might be one of our other documents, such as:

In this case, the chapters line up because they're all on one page, and the doc is only composed of those chapters. The handbooks have a different structure than the one-page guides. The renumbering follows the same principle, but there are higher-level divisions than just chapters, hence the numbering not always following along.

3. I fixed the MCE description. Seems that's changed a bit in recent kernels.

Thanks for the suggestions!