[prev in list] [next in list] [prev in thread] [next in thread] 

List:       gentoo-doc
Subject:    Re: [gentoo-doc] Gentoo Handbook part II, two chapters "finished"
From:       Sven Vermeulen <swift () gentoo ! org>
Date:       2003-11-27 14:52:59
[Download RAW message or body]


On Thu, Nov 27, 2003 at 02:59:45PM +0100, Peter Gantner wrote:
> In code listing 2 the note is not very clear I would write:
> 
> > ( --classify will append a special character to denote the 
> filetype, e.g append a / to directories)

I've taken your suggestion into account, but changed it differently. I now
talk about "ls --classify" before the code listing starts.
 
> Paragraph "Viewing the ChangeLog":
> emerge --changelog does not work for me, for whatever reason.

It should work. If it doesn't, then it is a bug (probably a missing ChangeLog
file).

> Still, once it does work, a short explanation of the output/a 
> changelog below listing 8 should be added.

I don't see why a user wouldn't understand the following:


.  04 Aug 2003; Brad Laue <brad@gentoo.org> mozilla-1.4-r3.ebuild:
.  Stable on x86
.
.  03 Aug 2003; Brad Laue <brad@gentoo.org> mozilla-1.4-r3.ebuild:
.  Filter the same flags firebird does.

We can't really explain the "Stable on x86" and "Filter the ... does." as
these are texts that are not defined anywhere (it is just what the developer
writes), and all the rest is very trivial.

> > Searching through Portage is nice, but if you don't update your
> > Portage Tree regularly, you will be stuck with the packages and
> > versions available on your system. This means that your package
> > versions will get outdated pretty soon, and you might be missing
> > bugfixes and remedies for possible security problems which are 
> > commited constantly to the on-line Portage Mirrors.

I've updated the text to use something like this. I don't talk about
"committed constantly" because that would leave the impression that Gentoo is
as leak as a badly-managed Windows server.

I have also used "will be missing bugfixes" instead of "might" as (s)he will
undoubtedly miss bugfixes if (s)he doesn't update Portage :)
 
> Chapter 2d:
> In "ARCH or not?" we should perhaps cater to the clueless:
> 
> < In other words, for x86-based systems you have x86 and ~x86, for 
> < ppc-based systems you have ppc and ~ppc etc.
> 
> > In other words, for x86 (Intel) based systems you have x86 and
> > ~x86, for ppc (PowerPC) based systems you have ppc and ~ppc etc.

The user has already installed Gentoo, so I don't know why (s)he would still
be baffled by x86/ppc/...

Also, x86 == (Intel|AMD|Transmeta|ViA) and perhaps even more. Listing just
"Intel" would lead to problems, listing them all to a bloated document.
 
Wkr,
	Sven Vermeulen

-- 
 ^__^   And Larry saw that it was Good.
 (oo)                                      Sven Vermeulen
 (__)   http://www.gentoo.org              Gentoo Documentation Project

[Attachment #3 (application/pgp-signature)]

[prev in list] [next in list] [prev in thread] [next in thread]