update installation instructions

pollen/private/ts.rktd

@@ -1 +1 @@
-1516572991
+1516651656

pollen/scribblings/installation.scrbl

@@ -5,7 +5,7 @@
 @(define my-eval (make-base-eval))
 @(my-eval `(require pollen pollen/file))
 
-@(define (short-version) (car (regexp-match #px"^\\d.\\d" (version))))
+@(define (short-version) (car (regexp-match #px"^\\d+.\\d+" (version))))
 
 @title{Installation}
 
@@ -25,24 +25,35 @@ After the initial download, Pollen does not require a network connection.
 
 @item{@link["http://download.racket-lang.org/"]{Download and install Racket}, which includes DrRacket. (Of course, you're welcome to use your preferred text editor, but the tutorials will assume you're using DrRacket.)}
 
-@item{Linux and OS X users: update your system @envvar{PATH} to include @filepath{/path-to-racket-installation/bin/}. Then, from the terminal, you'll be able to run @exec{racket} and @exec{raco} (see @other-doc['(lib "scribblings/raco/raco.scrbl")]).}
+@item{@bold{Windows} users: when you see instructions that reference @exec{racket} or @exec{raco}, I'll trust you to convert into the appropriate command for your system. Assuming defaults, it's likely to be @filepath{C:\Program Files\Racket\raco} (include the surrounding quotes in the command).}
 
+@item{@bold{Linux} and @bold{Mac OS} users: update your system @envvar{PATH} variable to include the path to Racket's newly installed @filepath{bin} directory. Then, from the terminal, you'll be able to run @exec{racket} and @exec{raco} (see @other-doc['(lib "scribblings/raco/raco.scrbl")]).}
 
-@item{OS X users who haven't altered your @envvar{PATH} before: don't panic. You need to add the full path to Racket's @racket[bin] directory to the @filepath{/etc/paths} file on your system. You can do this with the following terminal command (which will ask you for your password):
+@item{@bold{Mac OS} users who haven't altered your @envvar{PATH} before: don't panic. You need to add the full path of Racket's @filepath{bin} subdirectory to the @filepath{/etc/paths} file on your system. 
 
-@terminal{sudo sh -c 'echo "/Applications/Racket v@(short-version)/bin" >> /etc/paths'}
+First, confirm that your Racket instal­la­tion works. Open your new Racket direc­tory and launch­ DrRacket. If DrRacket works, then your Racket installa­tion is sound.
 
-Of course, @filepath{/Applications/Racket v@(short-version)/bin} should be changed if necessary to represent the actual location and version of your Racket installation.}
+Second, verify the full path to the @filepath{bin} sub­di­rec­tory of your new Racket direc­tory. If you put this direc­tory in @filepath{Applications} as rec­om­mended, the path will be:
 
+@terminal{/Applications/Racket v@(short-version)/bin}
 
-@item{To check that you did it correctly, try typing @exec{racket} on your command line, and you should see something like this:
+Third, copy the terminal command below, paste it into your terminal, and type return. (It will ask you for your password, because the @filepath{paths.d} directory is restricted to administrators.)
+
+@terminal{sudo sh -c 'echo "/Applications/Racket v@(short-version)/bin" >> /etc/paths.d/racket'
+}
+
+Of course, @filepath{/Applications/Racket v@(short-version)/bin} in this command should be edited as necessary to represent the actual location and version of your Racket installation.}
+
+@item{@bold{Mac OS} users who are still confused: here's an @link["https://beautifulracket.com/setting-the-mac-os-path.html"]{even gentler walkthrough}.}
+
+@item{@bold{Linux}, @bold{Mac OS}, and @bold{Windows} users: try typing @exec{racket} on your command line, and you should see something like this:
 
 @terminal{~ : racket
 Welcome to Racket v.@(version).
 >
 }
 
-Type @exec{ctrl+D} to exit.
+If so, all is well. Type @exec{ctrl+D} to exit (or @exec{(exit)} on Windows).
 
 But if you get an error like this:
 
@@ -53,8 +64,9 @@ You have a deeper problem with your Racket installation that needs adjustment be
 }
 
 
-@item{Then, from the command line, install Pollen:
+@item{Then install Pollen. Your first option is to install it using @exec{raco} on the command line:
-@commandline{raco pkg install pollen}
+
+@terminal{raco pkg install pollen}
 
 To check that it worked, try typing @exec{raco pollen test} on the command line, and you should see this:
 
@@ -69,18 +81,16 @@ But if you get:
 
 You'll need to fix the problem before proceeding, most likely by reinstalling Pollen.
 
-
-@margin-note{Windows users, when you see instructions that reference @exec{raco}, I'll trust you to convert into the appropriate command for your system. Assuming defaults, it's likely to be @filepath{C:\Program Files\Racket\raco} (include the surrounding quotes in the command).}
-
-
 }
 
-@item{Alternatively, you can install Pollen from inside DrRacket with the @menuitem["File" "Install Package ..."] command, and then relaunching DrRacket.}
+@item{Your other option is to install Pollen from inside DrRacket. Use the menu command @menuitem["File" "Install Package ..."]. Type @exec{pollen} in the box and click @exec{Install}. When it's done, relaunch DrRacket.}
+
+@item{Either way, Pollen's HTML documentation will be automatically installed. One way to reach the documentation:
 
-@item{Either way, Pollen's documentation will be automatically installed.}
+@terminal{raco docs pollen}}
 
 @item{After that, you can also update the package from the command line:
-@commandline{raco pkg update --update-deps pollen}
+@terminal{raco pkg update --update-deps pollen}
 
 Updating is optional. Major updates may have backward-incompatible changes, so you might want to consult the current @secref["version-notes"] before plunging in. The documentation for the newest version of Pollen is @link["http://pkg-build.racket-lang.org/doc/pollen/"]{available online} and refreshed daily.