From 8b1f79ba073f749bfd698aa66148896a5097521a Mon Sep 17 00:00:00 2001 From: Matthew Butterick Date: Mon, 22 Jan 2018 15:07:36 -0500 Subject: [PATCH] update installation instructions --- pollen/private/ts.rktd | 2 +- pollen/scribblings/installation.scrbl | 42 +++++++++++++++++---------- 2 files changed, 27 insertions(+), 17 deletions(-) diff --git a/pollen/private/ts.rktd b/pollen/private/ts.rktd index c2edf65..ac3df7b 100644 --- a/pollen/private/ts.rktd +++ b/pollen/private/ts.rktd @@ -1 +1 @@ -1516572991 +1516651656 diff --git a/pollen/scribblings/installation.scrbl b/pollen/scribblings/installation.scrbl index efcf934..0efa114 100644 --- a/pollen/scribblings/installation.scrbl +++ b/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: -@commandline{raco pkg install pollen} +@item{Then install Pollen. Your first option is to install it using @exec{raco} on the command line: + +@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.