diff --git a/info.rkt b/info.rkt index 0341758..e66ec2d 100644 --- a/info.rkt +++ b/info.rkt @@ -1,7 +1,7 @@ #lang info (define collection 'multi) -(define version "0.9.914.48615") +(define version "1.0") (define deps '("base" "txexpr" "sugar" ("markdown" #:version "0.18") "htdp" "at-exp-lib" "html-lib" "rackjure" "web-server-lib" "scribble-text-lib" "rackunit-lib" "gui-lib")) diff --git a/pollen/private/ts.rktd b/pollen/private/ts.rktd index dd7160c..9071e2f 100644 --- a/pollen/private/ts.rktd +++ b/pollen/private/ts.rktd @@ -1 +1 @@ -1454358615 +1454367371 diff --git a/pollen/private/update-info.rkt b/pollen/private/update-info.rkt index 6555ee8..1cd7fed 100644 --- a/pollen/private/update-info.rkt +++ b/pollen/private/update-info.rkt @@ -6,5 +6,5 @@ (module+ main (define str (file->string info-file)) (define newstr - (regexp-replace #rx"\\(define version .*?\\)" str (format "(define version ~v)" pollen:version))) + (regexp-replace #rx"\\(define version .*?\\)" str (format "(define version ~v)" pollen:version-strict))) (display-to-file newstr info-file #:exists 'replace)) \ No newline at end of file diff --git a/pollen/private/version.rkt b/pollen/private/version.rkt index 67b34b1..d8a8787 100644 --- a/pollen/private/version.rkt +++ b/pollen/private/version.rkt @@ -1,26 +1,20 @@ #lang racket/base (require racket/file racket/format racket/runtime-path) -(provide pollen:version) +(provide pollen:version pollen:version-strict) (define-runtime-path ts-file "ts.rktd") -(define ts (file->value ts-file)) +(define major-version 1) +(define minor-version 0) -(define (convert str) - (apply string-append - (for/list ([c (in-string str)]) - (define c-int (char->integer c)) - (~a (integer->char (+ c-int (if (<= (char->integer #\0) c-int (char->integer #\9)) - (- (char->integer #\a) (char->integer #\0)) - 10))))))) +(define pollen:version-strict (format "~a.~a" major-version minor-version)) -(define (get-version) - (define major-version 0) - (define minor-version 9) +(define (generate-full-version) (define pollen-birthday 1375340400) ; 8/1/2013, 12:00:00 AM GMT-7:00 DST (define seconds-per-year (* 60 60 24)) (define build-time (- (file->value ts-file) pollen-birthday)) - (define-values (build-days build-seconds) (quotient/remainder build-time seconds-per-year)) - (format "~a.~a.~a.~a" major-version minor-version build-days build-seconds)) + (define-values (build-days seconds-remainder) (quotient/remainder build-time seconds-per-year)) + (define minutes-remainder (quotient seconds-remainder 60)) + (format "~a.~a.~a" pollen:version-strict build-days minutes-remainder)) +(define pollen:version (generate-full-version)) -(define pollen:version (get-version)) \ No newline at end of file diff --git a/pollen/scribblings/installation.scrbl b/pollen/scribblings/installation.scrbl index eac802e..7d91cfc 100644 --- a/pollen/scribblings/installation.scrbl +++ b/pollen/scribblings/installation.scrbl @@ -1,6 +1,6 @@ #lang scribble/manual -@(require scribble/eval pollen/render pollen/setup (for-label racket (except-in pollen #%module-begin) pollen/setup sugar)) +@(require scribble/eval pollen/render pollen/setup pollen/private/version "mb-tools.rkt" (for-label racket (except-in pollen #%module-begin) pollen/setup sugar)) @(define my-eval (make-base-eval)) @(my-eval `(require pollen pollen/file)) @@ -8,16 +8,77 @@ @title{Installation} -@link["http://download.racket-lang.org/"]{Install Racket}, which includes DrRacket. +@section{Prerequisites} -Linux and Mac users: update your @envvar{PATH} to include @filepath{/path-to-new-racket-directory/bin/}. Then you'll have access to @exec{raco} (see @other-doc['(lib "scribblings/raco/raco.scrbl")]). +Pollen will run on OS X, Linux, or Windows. -Mac users who haven't done this before: @link["http://architectryan.com/2012/10/02/add-to-the-path-on-mac-os-x-mountain-lion/"]{these instructions} are simple and accurate. +Pollen is not a self-contained GUI program like Adobe InDesign. It's a software package that runs atop the Racket language environment (also a free download). -Windows users, I'll trust you to convert @exec{raco} 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). +Your three main tools in Pollen will be a text editor (for those starting out, I recommend @other-doc['(lib "scribblings/drracket/drracket.scrbl")]), a terminal window, and a web browser. The terminal commands you'll be using are simple, but if you haven't used your terminal window before, this is the moment to learn where it is. -Then, from the command line, install Pollen: +After the initial download, Pollen does not require a network connection. + +@section{How to install} + +@itemlist[ + +@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")]). + +@margin-note{OS X users who haven't altered your @envvar{PATH} before: don't panic. @link["http://architectryan.com/2012/10/02/add-to-the-path-on-mac-os-x-mountain-lion/"]{These instructions} are simple and accurate.} + +To check that you did it correctly, 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. + +} + +@item{Windows users, when you see instructions that reference @exec{raco} — like the one below — 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{Then, from the command line, install Pollen: @commandline{raco pkg install pollen} -After that, you can update the package from the command line: -@commandline{raco pkg update --update-deps pollen} \ No newline at end of file +To check that it worked, try typing @exec{raco pollen version} on the command line, and you should see something like this: + +@terminal{~ : raco pollen version +@|pollen:version| +~ : +} + + +} + +@item{Alternatively, you can install Pollen from inside DrRacket with the @onscreen{File > Install Package ...} command.} + +@item{Either way, Pollen's documentation will be automatically installed.} + +@item{After that, you can also update the package from the command line: +@commandline{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. + +} + +] + +@section{Beyond that} + +Pollen doesn't install anything on your machine other than the Racket packages it relies on. It does not gather any information about you or your project. Your data belongs to you. I won't know that you're using Pollen unless you tell me. + +Pollen's built-in @seclink["Using_the_project_server" + #:doc '(lib "pollen/scribblings/pollen.scrbl")]{project web server} is a real web server, however. Be mindful if you're using it on a machine visible on a public network. + + This project server is primarily a development & previewing tool. You do not need it to deploy Pollen projects (which generally compile down to a set of static files). + +In general, I subscribe to the view that software should let you do what you want, not enroll you in a nanny state. Pollen is, in part, a programming language. Like all programming languages, it will let you do things that are incredibly clever. And also miserably stupid. But that is how we learn. + +I've been using Pollen daily for several years (and will continue to do so, because my main work is writing). I've made Pollen available because a) I'm certain that others have had the same frustrations that I have, and b) feature suggestions and bug reports make it more useful for everyone. + +I hope you enjoy using it. If you get stuck on something not covered here, see @secref["Getting_more_help" #:doc '(lib "pollen/scribblings/pollen.scrbl")]. + diff --git a/pollen/scribblings/pollen.scrbl b/pollen/scribblings/pollen.scrbl index ddabacb..c40258e 100644 --- a/pollen/scribblings/pollen.scrbl +++ b/pollen/scribblings/pollen.scrbl @@ -1,41 +1,33 @@ #lang scribble/manual -@(require scribble/eval pollen/setup (for-label racket (except-in pollen #%module-begin) pollen/setup)) - -@(define my-eval (make-base-eval)) -@(my-eval `(require pollen)) - - @title[#:style 'toc]{Pollen: the book is a program} - - @author[(author+email "Matthew Butterick" "mb@mbtype.com")] @defmodulelang[pollen] +Pollen is a publishing system that helps authors create functional and beautiful digital books. -Pollen is a publishing system that helps authors create beautiful and functional web-based books. Pollen includes tools for writing, designing, programming, testing, and publishing. - -I used Pollen to create my books @link["http://practicaltypography.com"]{@italic{Butterick's Practical Typography}} and @link["http://typographyforlawyers.com"]{@italic{Typography for Lawyers}}. Sure, go take a look. Are they better than the last digital book you encountered? Yes they are. Would you like your book to look like that? If so, keep reading. +I created Pollen so I could make my web-based books @link["http://practicaltypography.com"]{@italic{Butterick's Practical Typography}} and @link["http://typographyforlawyers.com"]{@italic{Typography for Lawyers}}. Sure, go take a look. Are they better than the last digital books you encountered? Yes they are. Would you like your next digital book to look like that? If so, keep reading. -At the core of Pollen is an argument: -@itemlist[#:style 'unordered +The core idea of Pollen is an argument: +@itemlist[#:style 'ordered -@item{First, that digital books should be the best books we've ever had. So far, they're not even close.} +@item{Digital books should be the best books we've ever had. So far, they're not even close.} -@item{Second, that because digital books are software, an author shouldn't think of a book as merely data. @bold{The book is a program.}} +@item{Because digital books are software, an author shouldn't think of a book as merely data. @bold{The book is a program.}} -@item{Third, that the way we make digital books better than their predecessors is by exploiting this programmability.}] +@item{The way we make digital books better than their predecessors is by exploiting this programmability.}] That's what Pollen is for. -Not that you need to be a programmer to use Pollen. On the contrary, the Pollen language is markup-based, so you can write & edit text naturally. But when you want to automate repetitive tasks, add cross-references, or pull in data from other sources, you can access a full programming language from within the text. +Not that you need to be a programmer to start using Pollen. On the contrary, the Pollen language is markup-based, so you can write & edit text naturally. But when you want to automate repetitive tasks, add cross-references, or pull in data from other sources, you can access a full programming language from within the text. -That language is Racket. I chose Racket because while the idea for Pollen had been with me for several years, it simply wasn't possible to build it with other languages. So if it's unfamiliar to you, don't panic. It was unfamiliar to me. Once you see what you can do with Pollen & Racket, you may be persuaded. I was. +That language is @link["http://racket-lang.org"]{Racket}. I chose Racket because it has some unique features that made Pollen possible. So if it's unfamiliar to you, don't panic. It was unfamiliar to me. Once you see what you can do with Racket & Pollen, you may be persuaded. I was. Or, if you can find a better digital-publishing tool, use that. But I'm never going back to the way I used to work. + @local-table-of-contents[] @@ -57,5 +49,6 @@ Or, if you can find a better digital-publishing tool, use that. But I'm never go @include-section["more-help.scrbl"] @include-section["acknowledgments.scrbl"] @include-section["license.scrbl"] +@include-section["version-history.scrbl"] -@index-section[] +@index-section[] \ No newline at end of file diff --git a/pollen/scribblings/quick.scrbl b/pollen/scribblings/quick.scrbl index 451ce28..8edc6c4 100644 --- a/pollen/scribblings/quick.scrbl +++ b/pollen/scribblings/quick.scrbl @@ -1,15 +1,15 @@ #lang scribble/manual -@(require "mb-tools.rkt" (for-label racket pollen/template)) +@(require "mb-tools.rkt" pollen/private/version (for-label racket pollen/template)) @title[#:tag "quick-tour"]{Quick tour} @section{Creating a source file} -Assuming you've installed Racket & Pollen, launch DrRacket. +Assuming you've @seclink["Installation"]{installed Racket & Pollen}, launch DrRacket. -Open a new document. Change the top line to: +Start a new document. Change the top line to: @codeblock{ #lang pollen @@ -31,7 +31,7 @@ Click the @onscreen{Run} button. In the interactions window, you'll see the resu @repl-output{Hello world} -Not bad. I think Pollen just won the @link["http://en.wikipedia.org/wiki/List_of_Hello_world_program_examples"]{Hello World Tournament}. +Not bad. I think Pollen just won the @link["http://helloworldcollection.de"]{Hello World Tournament}. You can work with Pollen source files in any text editor, including Emacs or Sublime Text. The key advantage of DrRacket is that you can preview the results by running the file. @@ -67,11 +67,9 @@ Save this file as @filepath{hello.txt.pp} in any convenient directory. The deskt Open a terminal window and issue two commands: @terminal{ -> cd [directory containing your file] +> cd /directory/containing/your/hello-file > raco pollen render hello.txt.pp} -@margin-note{Windows users, I'll trust you to convert @exec{raco} 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).} - After a moment, a new file will appear called @filepath{hello.txt}. Let's see what's in it: @terminal{ @@ -81,6 +79,8 @@ Breakfast in America Take the Long Way Home } +@margin-note{If @exec{raco} doesn't work, it's probably because the @envvar{PATH} wasn't set up correctly during @secref["Installation"].} + You've just learned three things: @itemlist[ @@ -92,10 +92,14 @@ You've just learned three things: @item{The name of the output file is the same as the source file, minus the Pollen source extension. So @filepath{hello.txt.pp} is rendered to a file called @filepath{hello.txt}.} ] -Try editing the text in @filepath{hello.txt.pp} and running @commandline{raco pollen render hello.txt.pp} again. The old @filepath{hello.txt} will be replaced with a new one showing your changes. Thus, now you've learned a fourth thing: +Try editing the text in @filepath{hello.txt.pp} and running the command again: + +@commandline{raco pollen render hello.txt.pp} + +The old @filepath{hello.txt} will be replaced with a new one showing your changes. So now you've learned a fourth thing: @itemlist[ -@item{Pollen works by rendering output files from source files. Output files can be overwritten. Therefore, you should only make edits to your source files.} +@item{Pollen works by rendering output files from source files. Output files can be overwritten. Therefore, you should only edit your source files.} ] @@ -106,19 +110,19 @@ You just saw two ways to view the output of a Pollen source file — first, you Now here's a third: the Pollen project server. To start the project server, return to your terminal and issue two commands: @terminal{ -> cd [directory containing your hello.txt.pp file] +> cd /directory/containing/your/hello-file > raco pollen start} After a moment, you'll see the startup message: @terminal{ -Welcome to Pollen 0.001 (Racket @(version)) +Welcome to Pollen @|pollen:version| (Racket @(version)) Project root is /path/to/your/directory Project server is http://localhost:8080 (Ctrl-C to exit) Project dashboard is http://localhost:8080/index.ptree Ready to rock} -Open a web browser and point it at @link-tt{http://localhost:8080/index.ptree}. The top line of the window will say @tt{Project root} and show the name of the starting directory. Below that will be a listing of the files in the directory. +Open a web browser and point it at the project dashboard, which by default is @link-tt{http://localhost:8080/index.ptree}. The top line of the window will say @tt{Project root} and show the name of the starting directory. Below that will be a listing of the files in the directory. Among them will be @filepath{hello.txt}, with a greyed-out @filepath{.pp} extension. Click on it, and you'll be taken to @link-tt{http://localhost:8080/hello.txt}, where you'll see: @@ -145,14 +149,14 @@ Mean Street Panama Hear About It Later} -Notice what happened — the Pollen project server dynamically regenerated the output file (@filepath{hello.txt}) from the source file (@filepath{hello.txt.pp}) after you edited the source. If you like, try making some more changes to @filepath{hello.txt.pp}, and reloading the browser to see the updates in @filepath{hello.txt}. +Notice what happened — the Pollen project server dynamically regenerated the output file (@filepath{hello.txt}) from the source file (@filepath{hello.txt.pp}) after you edited the source. If you like, try making some more changes to @filepath{hello.txt.pp}, and reloading the browser to see the updates in @filepath{hello.txt}. The project server will regenerate the file whenever it changes. @section{Intermission} That covers input & output. Now let's circle back and look at what else you can do with Pollen (beyond the epic achievement of displaying plain text in a web browser). -For the rest of this tutorial, I recommend keeping two windows on screen: a web-browser window pointed at your project server (the main URL is @link-tt{http://localhost:8080/index.ptree}) and the DrRacket editing window. +For the rest of this tutorial, I recommend keeping two windows on screen: a web-browser window pointed at your @link["http://localhost:8080/index.ptree"]{project dashboard}, and the DrRacket editing window. @section{Pollen as a preprocessor} @@ -170,14 +174,14 @@ For instance, HTML. In DrRacket, create a new file called @filepath{margin.html. The @filepath{.pp} file extension — which you saw before, with @filepath{hello.txt.pp} — stands for ``Pollen preprocessor.'' You can use the Pollen preprocessor with any text-based file by inserting @code{#lang pollen} as the first line, and adding the @filepath{.pp} file extension. -But for now, go to your @link["http://localhost:8080/index.ptree"]{project dashboard} and click @link["http://localhost:8080/margin.html"]{@filepath{margin.html}}. You should see a black box containing the text ``5em is the inset.'' +But for now, go to your @link["http://localhost:8080/index.ptree"]{project dashboard} and click @link["http://localhost:8080/margin.html"]{@filepath{margin.html}}. You should see a black box containing the text ``@tt{5em is the inset.}'' Suppose you want to change the inset to 30%. Without a preprocessor, you'd have to search & replace each value. But with a preprocessor, you can move the inset value into a variable, and update it from that one location. So first, introduce a variable called @code{my-inset} by using the @racket[define] command: @fileblock["margin.html.pp" @codeblock{ #lang pollen -◊define[my-inset]{30%} +◊(define my-inset "30%")
10em is the inset. @@ -185,28 +189,22 @@ Suppose you want to change the inset to 30%. Without a preprocessor, you'd have The @code{◊} character is called a @italic{lozenge}. In Pollen, the lozenge is a special character used to denote anything that Pollen should interpret as a command (rather than plain text). -@margin-note{How to type a lozenge: -If you're using DrRacket, click the @onscreen{Insert command char} button on the toolbar to insert a lozenge in your code. - -If you're not: -@(linebreak)@bold{Mac}: option + shift + V -@(linebreak)@bold{Windows}: holding down alt, type 9674 on the num pad -@(linebreak)@bold{Ubuntu}: ctrl + shift + U, then 25CA} +If you're using DrRacket, you can insert a lozenge by clicking the @onscreen{Insert command char ◊} button at the top of your source window. (If you're not using DrRacket, see @seclink["The_lozenge_glyph____"]{these instructions}.) -Thus, the command @code{◊define[my-inset]{30%}} means ``create a variable called @code{my-inset} and give it the value @code{30%}.'' +Thus, the command @code{◊(define my-inset "30%")} means ``create the variable @code{my-inset} and assign it the value @racket{30%}.'' -Now you can insert the variable into the HTML like so, this time using the ◊ character with the variable name in the two places the value needs to appear: +Now you can insert the variable into the HTML, this time using the special ◊ character with the variable name in the two places the value needs to appear: @fileblock["margin.html.pp" @codeblock{ #lang pollen -◊define[my-inset]{30%} +◊(define my-inset "30%") ◊my-inset is the inset. }] -Now reload @link["http://localhost:8080/margin.html"]{@filepath{margin.html}}. You'll see that the size of the margin has changed (because of the change to the @code{style} attribute) and so has the text of the HTML. If you like, try editing @code{my-inset} with different values and reloading the page. You can also try using @racket[define] to create another variable (for instance, to change the color of the box border). +In your web browesr, reload @link["http://localhost:8080/margin.html"]{@filepath{margin.html}}. You'll see that the size of the margin has changed (because of the change to the @code{style} attribute) and so has the text of the HTML. If you like, try editing @code{my-inset} with different values and reloading the page. You can also try using @racket[define] to create another variable (for instance, to change the color of the box border). Still, this is the tiniest tip of the iceberg. The Pollen preprocessor gives you access to everything in the Racket programming language — including string manipulation, math functions, and so on. @@ -214,7 +212,7 @@ Still, this is the tiniest tip of the iceberg. The Pollen preprocessor gives you When used as a preprocessor, Pollen's rule is that what you write is what you get. But if you're targeting HTML, who wants to type out all those @code{