You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
pollen/scribblings/pollen.scrbl

72 lines
2.8 KiB
Plaintext

11 years ago
#lang scribble/manual
11 years ago
@(require scribble/eval pollen/world (for-label racket (except-in pollen #%module-begin) pollen/world))
11 years ago
11 years ago
@(define my-eval (make-base-eval))
@(my-eval `(require pollen))
11 years ago
11 years ago
@title{Pollen: the book is a program}
11 years ago
@author[(author+email "Matthew Butterick" "mb@mbtype.com")]
11 years ago
Pollen is a publishing system that helps authors create beautiful and functional web-based books. Pollen is a package of tools for writing, designing, programming, testing, and publishing.
11 years ago
I used Pollen to make my book @link["http://practicaltypography.com"]{Butterick's Practical Typography}. If that looks better than the last digital book you encountered, read on.
11 years ago
Pollen is built around two ideas. First, that digital books should be the best books we've ever had. (So far, they're not even close.) Second, that if digital books are software, authors shouldn't think of a book as merely data. The book is a program.
11 years ago
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 or add other features, you can access a full programming language from within the text.
11 years ago
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.
11 years ago
Or, if you can find a better digital book-publishing tool, use that. Personally, I'm never going back to the way I used to make web pages. After 20 years of web publishing, this is the best tool I've ever had.
11 years ago
@section{Installation}
11 years ago
Install Racket, which includes DrRacket.
11 years ago
Install Pollen from the command line:
@verbatim{raco pkg install pollen}
11 years ago
After that, you can update the package from the command line:
@verbatim{raco pkg update pollen}
11 years ago
@section{Pollen source formats}
11 years ago
@defmodulelang[pollen]
11 years ago
This puts Pollen into automatic mode, where the source file is interpreted according to the file extension.
11 years ago
If the file extension is ``@(format ".~a" world:markup-source-ext)'', the source is interpreted as @racket[pollen/markup].
11 years ago
If the file extension is ``@(format ".~a" world:preproc-source-ext)'', the source is interpreted as @racket[pollen/pre] (``pre'' stands for ``preprocessor'').
11 years ago
If the file extension is ``@(format ".~a" world:markdown-source-ext)'', the source is interpreted as @racket[pollen/markdown].
11 years ago
@defmodulelang[pollen/markup]
11 years ago
@defmodulelang[pollen/pre]
11 years ago
@defmodulelang[pollen/markdown]
11 years ago
@section{Rendering}
11 years ago
@defmodule[pollen/render]
11 years ago
@section{License & source code}
11 years ago
This module is licensed under the LGPL.
11 years ago
Source repository at @link["http://github.com/mbutterick/pollen"]{http://github.com/mbutterick/pollen}. Suggestions & corrections welcome.