From: John Darrington <john@darrington.wattle.id.au>
To: yoosty@gmail.com
Cc: guix-devel@gnu.org
Subject: Re: [PATCH] Quick-start guide
Date: Mon, 13 Jun 2016 02:40:10 +0200 [thread overview]
Message-ID: <20160613004010.GA28724@jocasta.intra> (raw)
In-Reply-To: <CAGSLf80VTq42L=oop9dZcZRJz3ROGPxc0AwUFcjSCDxGSpYm9Q@mail.gmail.com>
[-- Attachment #1: Type: text/plain, Size: 6550 bytes --]
On Sat, Jun 04, 2016 at 01:00:17PM -0700, yoosty@gmail.com wrote:
Howdy!
This is my first submission, please be gentle ;)
Input is definitely welcome.
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 208c6af..46c652f 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -18,6 +18,7 @@ the @file{CODE-OF-CONDUCT} file in the source tree.
@menu
* Building from Git:: The latest and greatest.
* Running Guix Before It Is Installed:: Hacker tricks.
+* Quick Setup:: The quick and easy tools
* The Perfect Setup:: The right tools.
* Coding Style:: Hygiene of the contributor.
* Submitting Patches:: Share your work.
@@ -153,6 +154,75 @@ the @file{/root/.config/guix/latest} symlink to point
to
@command{guix} as your user does.}
+@node Quick Setup
+@section Quick Setup
+
+So you just want the quick-and-dirty guide? Assuming you have some
familiarity
+with GNU/Linux systems in general and have installed one several times
before
+you can probably get started with a few notes while citing
+@pxref{GNU Distribution} as necessary. As this is a quick-setup guide
we'll use
+some example defaults.
+The general idea is that you will:
What is the purpose of the above paragraph? It does not convey any information
to the reader. Whilst I think it is good to put the reader at ease, this is
overdoing it. Further, it is vague and overly conditional ("Assuming you have ...
you can probably ...") which will make the reader feel unsure of himself.
I would replace these three sentances by something short and to the point such
as "Setting up Guix involves the following steps:"
+@itemize
+@item @uref{https://gnu.org/software/guix/download/, Download} the USB
installer
+@item Transfer the image to a USB stick (@pxref{USB Stick Installation})
+using dd
+@item Boot the USB stick
+@item Configure @pxref{Preparing for Installation,Networking}
+@item Set your @xref{Preparing for Installation,Disk Partitioning}
+(using an msdos label instead of a gpt label might be easier at the moment)
+@item Mount your partitions (e.g. /mnt)
+@item Run (again, e.g. /mnt) @command{herd start cow-store /mnt}
+@item Create a system configuration file using
+@xref{Proceeding with the Installation} and
+@xref{Using the Configuration System} as guides. It is suggested to start
+with the bare-bones template as you can easily re-configure your system
+once it is up.
+@item Using /mnt/root/guix_configs/config00.scm as the example config file
+and /mnt as the example install mount point, run
+@command{guix system init /mnt/root/guix_configs/config00.scm /mnt}
+@item Cross your fingers and grab a beer
+@item If you're using reasonably new hardware and a bare-bones config
What do you mean by "bare-bones config" and what if the reader is not using one?
or not using new hardware?
+then guix should be done before your beverage and you can run
Else where you have written "Guix" rather than "guix".
+@command{reboot}
+@end itemize
+
+Now you should be ready to rock!
I recommend that you avoid cliches like this. Readers for whom English is a
second language, may not be familiar with such expressions. It might confuse
them. Similarly, with "cross your fingers and grab a beer". Instead, be
specific and say something like: "Installation will now proceed. It will take
several minutes. If you are using older hardware, then it may take somewhat
longer". And importantly, say what the user should see after the process has
completed.
+ Don't forget to set your user passwords.
How should the reader do that?
+
+Of course, you're not here just to have a working system are you, you want
Punctuation. Should read: "... are you? You want..."
+to dive in to the source, right? Let's take a quick look at that as well.
Again, expressions like "to dive in" might confuse some readers.
+This guide assumes that you have at least perused @pxref{Building from
Git}.
+First you might want to head to
+@uref{http://git.savannah.gnu.org/cgit/guix.git, the Guix Git page} and
browse
+around. We're going to assume that you utilized a bare-bones config as per
the
Who is "we" ? Again, what if he didn't use a "bare-bones config"?
+quick install guide above. In this short example you will be shown simply
+how to change the release version of Guix (not something you will likely do
+but an easy and fun example).
+
+@itemize
+@item Install git in to your user's profile: @command{guix package
--install git}
+@item Create a directory for your git checkout (e.g. @command{mkdir
~/git_repos})
+@item Clone the Guix repository:
+@command{cd ~/git_repos/; git clone git://git.sv.gnu.org/guix.git; cd guix}
+@item To make the simple version change:
+@code{AC_INIT([GNU Guix], [0.10.0], [bug-guix@@gnu.org], [guix],}
+to
+@code{AC_INIT([GNU Guix], [0.10.42], [bug-guix@@gnu.org], [guix],}
+@item Check your change with: @command{git diff configure.ac}
+@item Let Guix set up your Guix build
+environment:@command{guix environment guix}
+@item Build Guix:
+@command{./bootstrap ; ./configure --localstatedir=/var ; make}
+@item Run the daemon in a pre-installation environment:
+@command{sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild}
+@item Switch to a new terminal
+@item Check the pre-installation environement daemon's version:
+@command{./git_repos/guix/pre-inst-env guix --version}
+@item Your version output should be updated!
This sentance is not a part of the procedure. It should appear outside of the
@itemize block
+@end itemize
+
+
@node The Perfect Setup
@section The Perfect Setup
--
.:Justin:.
--
Avoid eavesdropping. Send strong encryted email.
PGP Public key ID: 1024D/2DE827B3
fingerprint = 8797 A26D 0854 2EAB 0285 A290 8A67 719C 2DE8 27B3
See http://sks-keyservers.net or any PGP keyserver for public key.
[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 181 bytes --]
prev parent reply other threads:[~2016-06-13 0:40 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-06-04 20:00 [PATCH] Quick-start guide yoosty
2016-06-08 12:47 ` Ludovic Courtès
2016-06-11 13:43 ` yoosty
2016-06-11 17:49 ` Leo Famulari
2016-06-12 15:14 ` myglc2
2016-06-12 20:46 ` Ludovic Courtès
2016-06-15 5:07 ` yoosty
2016-06-16 10:51 ` Ludovic Courtès
2016-06-24 4:55 ` yoosty
2016-06-24 12:36 ` Ludovic Courtès
2016-06-13 0:40 ` John Darrington [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://guix.gnu.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20160613004010.GA28724@jocasta.intra \
--to=john@darrington.wattle.id.au \
--cc=guix-devel@gnu.org \
--cc=yoosty@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).