From mboxrd@z Thu Jan 1 00:00:00 1970 From: Matthew Jordan Subject: Re: feedback as solicited by Guix manual (Section 7.1.5) Date: Tue, 31 May 2016 14:35:05 -0400 Message-ID: <87mvn6xehy.fsf@mailerver.i-did-not-set--mail-host-address--so-tickle-me> References: <574B8D1E.6080000@ethan-stefan.net> <20160531155854.GA27525@jasmine> <87oa7mxk8b.fsf@mailerver.i-did-not-set--mail-host-address--so-tickle-me> <20160531175659.GA17589@jasmine> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:43582) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1b7oWf-0002Na-Hb for guix-devel@gnu.org; Tue, 31 May 2016 14:36:26 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1b7oWc-0000a5-AX for guix-devel@gnu.org; Tue, 31 May 2016 14:36:25 -0400 Received: from forward4j.cmail.yandex.net ([5.255.227.22]:39945) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1b7oWa-0000YK-PZ for guix-devel@gnu.org; Tue, 31 May 2016 14:36:22 -0400 In-reply-to: <20160531175659.GA17589@jasmine> List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: Leo Famulari Cc: guix-devel@gnu.org I just looked ouver the installation part of the manual. > What parts do you think should be added to our manual? A number of these > steps are already covered in section 7.1 System Installation. That was mostly a copy paste from my notes. But what I wouldn't mind seeing in the manual is as follows; 1. Section 7.1.4.2 Networking; mentions using ifconfig, correct me if I"m wrong but isn't ifconfig considered deprecated? In which case iproute2 commands could be used; $ ip link show $ ip link set ens3 up 2. Section 7.1.4.3 Disk Partitioning It would be nice to indicate that you may need additional swap space to build the various packages that come with the install. Also sufficient space under /tmp is needed. In my case I had to bind mount the my tmp partition from the install target, and turn on the swap to achieve a successful install. I used these commands to achieve that. $ mount --bind /mnt/tmp /tmp $ swapon /dev/sda3 > Personally, I don't like putting instructions on how to use 3rd party > software in manuals such as ours (or the Gentoo or Arch manuals) unless > the information is very specific to how we use the software. > > In my opinion, if there is some deficiency with the 3rd party programs' > documentation, that documentation should be improved. > > Otherwise, knowledge is fragmented into a variety of places where it > probably won't be updated as the 3rd party software changes. Also, each > system's manual or wiki will invariably contain some info that is > specific to that system but not declared as such. And the new, external > documentation will probably not be reviewed by the upstream maintainers > for correctness, spreading bad advice across the internet. Finally, the > upstream manual will *still* not be improved. > > On the other hand, we should strive to make our system as easy to > install as possible. So, specific advice is most welcome! :) While these are valid points, and I have to say I agree with them. Even Gentoo and Arch (which are among some of the more challenging distros), do provide some example/recipe to assist with partitioning. I'm not saying we quote someone's manual, but someone might find it useful. We could always indicate that one should refer to upstream manual for the latest info, and still provide some steps based on a partitioning plan. I think this would be very helpful to those who may not be fully verse in partitioning. My first time using Gentoo was pretty decent because of the documentation provided. Here is the appropriate snippet from my notes; Paritioning plan Assumming disk is 20GiB Bootloader 2MiB /boot 300MiB ext2/4 Swap 1GiB / (rest of disk space) ext4 $ lsblk Start parted shell $ parted -a optimal /dev/sda (parted) unit MiB (parted) mklabel gpt (parted) mkpart primary 1MiB 3MiB (parted) name 1 grub (parted) set 1 bios_grub on (parted) print (parted) mkpart primary 3MiB 303MiB (parted) name 2 boot (parted) print Calculation on host with zsh shell $ ((mib = 1 * (1024 ** 1))) $ print ${mib} 1024 $ print $((mib + 303)) 1327 (parted) mkpart primary 303MiB 1327MiB (parted) name 3 swap (parted) print (parted) mkpart primary 1327MiB -1 (parted) name 4 root (parted) set 2 boot on (parted) print (parted) quit Of course feel free free to accept/reject these ideas, as they are just suggestions based on my state understanding when I first discovered Guix & GuixSD. I like to think of Guix as the next evolution of Linux from Arch Linux or Gentoo Linux ^_^. Respectfully, -- Matthew Jordan Sent with my mu4e Leo Famulari writes: > On Tue, May 31, 2016 at 12:31:16PM -0400, Matthew Jordan wrote: >> What follows are the steps I took to setup my GuixSD box. What I'm >> wondering is how would I go about contributing this in some way to the >> documentation? With some modification of course. > > What parts do you think should be added to our manual? A number of these > steps are already covered in section 7.1 System Installation. > >> I am just presenting this cause I had to look around a lot, such as the >> Gentoo Installation Manual, and Arch Linux manuals in addition to the >> Parted and Guix Manuals when I attempted my first install. Just thought >> it would be a good idea to perhaps have some solid example/steps in the >> Guix Manual for the installation. > > Personally, I don't like putting instructions on how to use 3rd party > software in manuals such as ours (or the Gentoo or Arch manuals) unless > the information is very specific to how we use the software. > > In my opinion, if there is some deficiency with the 3rd party programs' > documentation, that documentation should be improved. > > Otherwise, knowledge is fragmented into a variety of places where it > probably won't be updated as the 3rd party software changes. Also, each > system's manual or wiki will invariably contain some info that is > specific to that system but not declared as such. And the new, external > documentation will probably not be reviewed by the upstream maintainers > for correctness, spreading bad advice across the internet. Finally, the > upstream manual will *still* not be improved. > > On the other hand, we should strive to make our system as easy to > install as possible. So, specific advice is most welcome! :)