From 372c4775f73d04f9d15099cd3b34b4b242ac9064 Mon Sep 17 00:00:00 2001 From: Matthew Butterick Date: Mon, 5 May 2014 18:04:57 -0700 Subject: [PATCH] update docs --- doc/System_overview.html | 3 +- doc/doc-index.html | 2 +- doc/index.html | 2 +- doc/manual-style.css | 11 ++--- doc/racket.css | 10 +++-- scribblings/system.scrbl | 92 ++++++++++++++++++++++++++-------------- 6 files changed, 74 insertions(+), 46 deletions(-) diff --git a/doc/System_overview.html b/doc/System_overview.html index 9be45d8..4114919 100644 --- a/doc/System_overview.html +++ b/doc/System_overview.html @@ -1,2 +1,3 @@ -4 System overview
▼Pollen:   the book is a program
►4 System overview
On this page:
4.1 The book is a program
4.2 One language, multiple dialects
4.3 Development environment
4.4 A special data structure for HTML
4.5 Preprocessor source files
4.6 Templated source files
4.7 Utility source files
4.8 Pagetrees
4.9 Build & deploy
6.0.1.6
    ← prev  up  next → 

4 System overview

A summary of the key components & concepts of the Pollen publishing system and how they fit together. If you’ve completed the Quick tour, this will lend some context to what you saw. The next tutorials will make more sense if you read this first.

4.1 The book is a program

This is the core design principle of Pollen. Consistent with this principle, Pollen adopts the habits of software development in its functionality, workflow, and project management.

  • You are a programmer. Don’t panic. But let’s just admit it — if your book is a program, then you are, in part, programming it. You don’t have to know any programming to start using Pollen. But you’ll have to be willing to learn a few programming ideas. (Those who have programmed other template-based HTML generators may have to forget a few things.)

  • A Pollen project consists of source files + static files. A source file is a file that can be compiled to produce certain output. A static file is usable as it stands (e.g., an SVG file or webfont). Generally, the textual content of your book will live in source files, and other elements will be static files.

  • Source control is a good idea. Because Pollen projects are software projects, they can be easily managed with systems for source control and collaboration, like GitHub. If you’re a writer at heart, don’t fear these systems — they really do make revision & edit tracking easier than it is with Word or PDF files.

4.2 One language, multiple dialects

  • Everything is Racket. The Pollen system is built entirely in the Racket programming language. Some of your source files will be in Racket. Others will be in one of the Pollen language dialects. But under the hood, everything becomes Racket code. So if you plan to do any serious work in Pollen, you’ll want to learn some basics about Racket too (for instance Quick: An Introduction to Racket with Pictures).

  • The Pollen language is based on Scribble. Scribble is a variant of the Racket language that flips the usual programming syntax: instead of code with embedded textual content, a Scribble source file is text with embedded code (an idea borrowed from TeX). The Pollen language is adapted from Scribble. So most things that are true about Scribble are also true about Pollen (see Scribble: The Racket Documentation Tool).

  • The Pollen language is divided into dialects. The Pollen dialects share a common syntax and structure. But they’re different in details that makes them better adapted to certain types of source files (for instance, one dialect of Pollen understands Markdown; the others don’t). You can use whichever suits the task at hand.

4.3 Development environment

The Pollen development environment has two main pieces: the DrRacket code editor, and the Pollen project server.

  • Edit source files with DrRacket. DrRacket is Racket’s GUI code editor. Sure, you can also use a generic text editor. But DrRacket lets you immediately run your source file and see if it works. I know your favorite programming language doesn’t have that. But trust me, it’s very convenient.

  • Render & preview web pages with the Pollen project server. Pollen has a built-in development web server called the project server. After you start the project server, you can preview & test your web pages within a web browser with maximum accuracy. Everything is rendered to static HTML so you can see exactly what you’ll get.

  • One directory for everything. Rather than separating your source files and static files, Pollen keeps them all in one directory so it’s simple to make links between them.

4.4 A special data structure for HTML

X-expression

Tags can be tags

Or tags can be functions

4.5 Preprocessor source files

Lower level of abstraction

Work directly

Text output

Any kind of file!

4.6 Templated source files

Higher level of abstraction

Work indirectly

X-expression output

Markdown

Markup

Templates

4.7 Utility source files

Scribble

Null

4.8 Pagetrees

Navigation

Hierarchy

Subsetting

Build script

4.9 Build & deploy

Pollen is not a production server

Render & clone

    ← prev  up  next → 
 
\ No newline at end of file +4 System overview
▼Pollen:   the book is a program
►4 System overview
On this page:
4.1 The book is a program
4.2 One language, multiple dialects
4.3 Development environment
4.4 A special data structure for HTML
4.5 Pollen command syntax
4.6 The preprocessor
4.7 Templated source files
4.8 Pagetrees
6.0.1.6
    ← prev  up  next → 

4 System overview

A summary of the key components & concepts of the Pollen publishing system and how they fit together. If you’ve completed the Quick tour, this will lend some context to what you saw. The next tutorials will make more sense if you read this first.

4.1 The book is a program

This is the core design principle of Pollen. Consistent with this principle, Pollen adopts the habits of software development in its functionality, workflow, and project management.

  • You are a programmer. Don’t panic. But let’s just admit it — if your book is a program, then you are, in part, programming it. You don’t have to know any programming to start using Pollen. But you’ll have to be willing to learn a few programming ideas. (Those who have programmed other template-based HTML generators may have to forget a few things.)

  • A Pollen project consists of source files + static files. A source file is a file that can be compiled to produce certain output. A static file is usable as it stands (e.g., an SVG file or webfont). Generally, the textual content of your book will live in source files, and other elements will be static files.

  • Source control is a good idea. Because Pollen projects are software projects, they can be easily managed with systems for source control and collaboration, like GitHub. If you’re a writer at heart, don’t fear these systems — the learning curve is repaid by revision & edit tracking that’s much easier than it is with Word or PDF files.

4.2 One language, multiple dialects

  • Everything is Racket. The Pollen system is built entirely in the Racket programming language. Some of your source files will be in Racket. Others will be in one of the Pollen language dialects. But under the hood, everything becomes Racket code. So if you plan to do any serious work in Pollen, you’ll want to learn some basics about Racket too (for instance Quick: An Introduction to Racket with Pictures).

  • The Pollen language is based on Scribble. Scribble is a variant of the Racket language that flips the usual programming syntax: instead of code with embedded textual content, a Scribble source file is text with embedded code (an idea borrowed from TeX). The Pollen language is adapted from Scribble. So most things that are true about Scribble are also true about Pollen (see Scribble: The Racket Documentation Tool).

  • The Pollen language is divided into dialects. The Pollen dialects share a common syntax and structure. But they’re different in details that makes them better adapted to certain types of source files (for instance, one dialect of Pollen understands Markdown; the others don’t). Use whichever suits the task at hand.

4.3 Development environment

The Pollen development environment has three main pieces: the DrRacket code editor, the project server, and the command-line tool.

  • Edit source files with DrRacket. DrRacket is Racket’s GUI code editor. Sure, you can also use a generic text editor. But DrRacket lets you immediately run your source and see if it works.

  • Preview & test web pages with the Pollen project server. Pollen has a built-in development web server called the project server. After you start the project server, you can preview your web pages within any web browser, allowing you to test them with maximum accuracy.

  • Write the docs. The project server can recognize and render Scribble files, so you can use it as a previewing tool while you’re writing your documentation.

  • Render & deploy from the command line. Your Pollen project ultimately gets rendered to a set of static files (usually HTML and related assets). This can be controlled from the command line, so you can integrate it into other scripts.

4.4 A special data structure for HTML

Unlike other programming languages, Pollen (and Racket) internally represent HTML with something called an X-expression. An X-expression is simply a list that represents what in HTML is called an element, meaning a thing with an opening tag, a closing tag, and content in between. Like HTML elements, X-expressions can be nested. Unlike HTML elements, X-expressions have no closing tag, they use parentheses to denote the start and end, and text elements are put inside quotes.

For example, consider this HTML element:

<body><h1>Hello world</h1><p>Nice to <i>see</i> you.</p></body>

As a Racket X-expression, this would be written:

(body (h1 "Hello world") (p "Nice to " (i "see") " you."))

More will be said about X-expressions. But a couple advantages should be evident already. First, without the redundant angle brackets, the X-expression is more readable than the equivalent HTML. Second, an X-expression is preferable to representing HTML as a simple string, because it preserves the internal structure of the element.

4.5 Pollen command syntax

As mentioned above, a Pollen source file is not code with text embedded in it, but rather text with code embedded. (See ◊ command overview for more.)

  • If you can write text, you can program in Pollen. Really. As you already found out in the Quick tour, this is a valid Pollen program: +
    #lang pollen
    Hello world: how are you on this fine summer day?

  • Commands start with ◊. A simple rule: if a piece of text starts with ◊, it’s treated as a command; otherwise it’s treated as ordinary text.

  • Write commands in text mode or Racket mode. Commands can use two equivalent notation systems: either Pollen’s text-mode command syntax, or standard Racket syntax.

  • Everything in Racket is in Pollen too. This isn’t some dimwit “template language.” Racket is a fully provisioned programming language, and every Racket function is available in Pollen.

4.6 The preprocessor

The preprocessor is the simplest processing mode in Pollen.

  • Text output. The preprocessor scans the source for any Pollen commands, resolves them, and outputs the whole file as text.

  • Work with any text file. I hope this blows your mind a teeny bit. You can use the preprocessor with HTML, CSS, Markdown, JavaScript, XML, SVG, or any other text-based file (including source files of other programming languages).

  • Start quickly. Because it works with any text file, the preprocessor is an easy way to try out Pollen, because you can mix it into your workflow on an existing project, or even just one file.

4.7 Templated source files

If you want to apply a particular page format to multiple sources of content — as you would in a book — you can use Pollen templates.

  • Templates can be any format. Usually Pollen templates will be HTML. But they don’t have to be.

  • Markdown support. Pollen has a built-in Markdown parser, so you can import Markdown sources into a Pollen publication.

  • Custom markup. Pollen’s markup mode allows you the freedom to define your own markup tags and attach behavior to them.

  • Mix source types. Every text source is converted to an X-expression before going into a template. So it’s fine to have multiple kinds of text source in one project.

4.8 Pagetrees

Similar to a table of contents, a pagetree is a special Pollen source file that gets turned into a hierarchical list of pages.

  • Navigation. Pagetrees are used to provide navigation links within HTML templates (like previous, next, up, top).

  • Organization. Multiple pagetrees can be used to divide your project into subsets of pages that should be treated separately.

    ← prev  up  next → 
 
\ No newline at end of file diff --git a/doc/doc-index.html b/doc/doc-index.html index 324c6da..bf1ee25 100644 --- a/doc/doc-index.html +++ b/doc/doc-index.html @@ -1,2 +1,2 @@ -Index
▼Pollen:   the book is a program
    ← prev  up  next → 

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

 

“Now you have two problems”
#%top
->html
->markup-source-path
->null-source-path
->output-path
->pagenode
->preproc-source-path
->scribble-source-path
->template-source-path
A special data structure for HTML
Acknowledgments
Any command is valid
Backstory
Block
block-txexpr?
Build & deploy
Cache
cache-ref
cached-require
children
Command syntax using ◊
Creating a source file
current-cache
current-pagetree
Custom exports
Decode
decode
def/c
detect-linebreaks
detect-paragraphs
Development environment
Enter Racket
File
File formats
Further reading
get-template-for
has-markup-source?
has-null-source?
has-preproc-source?
has-scribble-source?
has-template-source?
has/is-markup-source?
has/is-null-source?
has/is-preproc-source?
has/is-scribble-source?
has/is-template-source?
in-pagetree?
Inserting a comment
Inserting the value of a variable
Installation
Intermission
Invoking other functions
Invoking tag functions
License & source code
make-cache
make-tag-function
Making sure raco pollen works
Markdown (.pmd extension)
Markdown mode
Markup (.pm extension)
Markup mode
markup-source?
Module reference
Naming, saving, and rendering a source file
Navigation
next
next*
Null (.p extension)
null-source?
One language, multiple dialects
pagenode?
pagenodeish?
Pagetree
Pagetree (.ptree extension)
pagetree->list
pagetree-source?
pagetree?
Pagetrees
parent
path->pagenode
pollen
Pollen as a preprocessor
pollen/cache
pollen/decode
pollen/file
pollen/markdown
pollen/markup
pollen/pagetree
pollen/pre
pollen/ptree
pollen/render
pollen/tag
pollen/template
pollen/top
pollen/world
Pollen: the book is a program
preproc-source?
Preprocessor (.pp extension)
Preprocessor source files
previous
previous*
project-block-tags
PS for Scribble users
Quick tour
raco pollen
raco pollen clone
raco pollen help
raco pollen render
raco pollen start
register-block-tag
Render
render
render-batch
render-pagetree
render-to-file
render-to-file-if-needed
reset-cache
Rethinking the solution for digital books
Running a source file
Scribble (.scrbl extension)
scribble-source?
select
select*
select-from-doc
select-from-metas
siblings
smart-dashes
smart-quotes
Source formats
Standard exports
System overview
Tag
Template
template-source?
Templated source files
Templates
The better idea: a programming model
The book is a program
The command name
The end of the beginning
The golden rule
The lozenge glyph (◊)
The project server
The project-require.rkt file
The Racket arguments
The text argument
The two command modes: text mode & Racket mode
Top
Typography
Using raco pollen
Utilities
Utility formats
Utility source files
validate-pagetree
Web development and its discontents
What is Pollen?
whitespace/nbsp?
whitespace?
World
world:check-project-requires-in-render?
world:command-marker
world:current-server-extras-path
world:current-server-port
world:dashboard-css
world:decodable-extensions
world:default-pagetree
world:default-port
world:default-template-prefix
world:fallback-template
world:linebreak-separator
world:main-pollen-export
world:markdown-source-ext
world:markup-source-ext
world:meta-pollen-export
world:mode-auto
world:mode-markdown
world:mode-markup
world:mode-pagetree
world:mode-preproc
world:newline
world:null-source-ext
world:pagetree-root-node
world:pagetree-source-ext
world:paragraph-separator
world:paths-excluded-from-dashboard
world:preproc-source-ext
world:project-require
world:scribble-source-ext
world:server-extras-dir
world:template-meta-key
world:template-source-ext
◊ command overview

    ← prev  up  next → 
 
\ No newline at end of file +Index
▼Pollen:   the book is a program
    ← prev  up  next → 

Index

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

 

“Now you have two problems”
#%top
->html
->markup-source-path
->null-source-path
->output-path
->pagenode
->preproc-source-path
->scribble-source-path
->template-source-path
A special data structure for HTML
Acknowledgments
Any command is valid
Backstory
Block
block-txexpr?
Cache
cache-ref
cached-require
children
Command syntax using ◊
Creating a source file
current-cache
current-pagetree
Custom exports
Decode
decode
def/c
detect-linebreaks
detect-paragraphs
Development environment
Enter Racket
File
File formats
Further reading
get-template-for
has-markup-source?
has-null-source?
has-preproc-source?
has-scribble-source?
has-template-source?
has/is-markup-source?
has/is-null-source?
has/is-preproc-source?
has/is-scribble-source?
has/is-template-source?
in-pagetree?
Inserting a comment
Inserting the value of a variable
Installation
Intermission
Invoking other functions
Invoking tag functions
License & source code
make-cache
make-tag-function
Making sure raco pollen works
Markdown (.pmd extension)
Markdown mode
Markup (.pm extension)
Markup mode
markup-source?
Module reference
Naming, saving, and rendering a source file
Navigation
next
next*
Null (.p extension)
null-source?
One language, multiple dialects
pagenode?
pagenodeish?
Pagetree
Pagetree (.ptree extension)
pagetree->list
pagetree-source?
pagetree?
Pagetrees
parent
path->pagenode
pollen
Pollen as a preprocessor
Pollen command syntax
pollen/cache
pollen/decode
pollen/file
pollen/markdown
pollen/markup
pollen/pagetree
pollen/pre
pollen/ptree
pollen/render
pollen/tag
pollen/template
pollen/top
pollen/world
Pollen: the book is a program
preproc-source?
Preprocessor (.pp extension)
previous
previous*
project-block-tags
PS for Scribble users
Quick tour
raco pollen
raco pollen clone
raco pollen help
raco pollen render
raco pollen start
register-block-tag
Render
render
render-batch
render-pagetree
render-to-file
render-to-file-if-needed
reset-cache
Rethinking the solution for digital books
Running a source file
Scribble (.scrbl extension)
scribble-source?
select
select*
select-from-doc
select-from-metas
siblings
smart-dashes
smart-quotes
Source formats
Standard exports
System overview
Tag
Template
template-source?
Templated source files
Templates
The better idea: a programming model
The book is a program
The command name
The end of the beginning
The golden rule
The lozenge glyph (◊)
The preprocessor
The project server
The project-require.rkt file
The Racket arguments
The text argument
The two command modes: text mode & Racket mode
Top
Typography
Using raco pollen
Utilities
Utility formats
validate-pagetree
Web development and its discontents
What is Pollen?
whitespace/nbsp?
whitespace?
World
world:check-project-requires-in-render?
world:command-marker
world:current-server-extras-path
world:current-server-port
world:dashboard-css
world:decodable-extensions
world:default-pagetree
world:default-port
world:default-template-prefix
world:fallback-template
world:linebreak-separator
world:main-pollen-export
world:markdown-source-ext
world:markup-source-ext
world:meta-pollen-export
world:mode-auto
world:mode-markdown
world:mode-markup
world:mode-pagetree
world:mode-preproc
world:newline
world:null-source-ext
world:pagetree-root-node
world:pagetree-source-ext
world:paragraph-separator
world:paths-excluded-from-dashboard
world:preproc-source-ext
world:project-require
world:scribble-source-ext
world:server-extras-dir
world:template-meta-key
world:template-source-ext
◊ command overview

    ← prev  up  next → 
 
\ No newline at end of file diff --git a/doc/index.html b/doc/index.html index 74e1b95..416c1f1 100644 --- a/doc/index.html +++ b/doc/index.html @@ -1,3 +1,3 @@ Pollen: the book is a program
▼Pollen:   the book is a program
On this page:
Pollen:   the book is a program
6.0.1.6
    ← prev  up  next → 

Pollen: the book is a program

Matthew Butterick <mb@mbtype.com>

 #lang pollen package: pollen

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 book Butterick’s Practical Typography. Sure, go take a look. Is it better than the last digital book you encountered? Yes it is. Would you like your book to look like that? If so, keep reading.

At the core of Pollen is an argument: -

  • First, that digital books should be the best books we’ve ever had. So far, they’re not even close.

  • Second, that because digital books are software, an author shouldn’t think of a book as merely data. The book is a program.

  • Third, that 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.

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.

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.

    1 Installation

    2 Quick tour

      2.1 Creating a source file

      2.2 Running a source file

      2.3 Naming, saving, and rendering a source file

      2.4 The project server

      2.5 Intermission

      2.6 Pollen as a preprocessor

      2.7 Markdown mode

      2.8 Markup mode

      2.9 Templates

      2.10 PS for Scribble users

      2.11 The end of the beginning

    3 Backstory

      3.1 Web development and its discontents

      3.2 The better idea: a programming model

      3.3 “Now you have two problems”

      3.4 Rethinking the solution for digital books

      3.5 Enter Racket

      3.6 What is Pollen?

    4 System overview

      4.1 The book is a program

      4.2 One language, multiple dialects

      4.3 Development environment

      4.4 A special data structure for HTML

      4.5 Preprocessor source files

      4.6 Templated source files

      4.7 Utility source files

      4.8 Pagetrees

      4.9 Build & deploy

    5 Using raco pollen

      5.1 Making sure raco pollen works

      5.2 raco pollen

      5.3 raco pollen help

      5.4 raco pollen start

      5.5 raco pollen render

      5.6 raco pollen clone

    6 File formats

      6.1 Source formats

        6.1.1 Command syntax using ◊

        6.1.2 Any command is valid

        6.1.3 Standard exports

        6.1.4 Custom exports

        6.1.5 The project-require.rkt file

        6.1.6 Preprocessor (.pp extension)

        6.1.7 Markdown (.pmd extension)

        6.1.8 Markup (.pm extension)

        6.1.9 Pagetree (.ptree extension)

      6.2 Utility formats

        6.2.1 Scribble (.scrbl extension)

        6.2.2 Null (.p extension)

    7 ◊ command overview

      7.1 The golden rule

      7.2 The lozenge glyph (◊)

      7.3 The two command modes: text mode & Racket mode

        7.3.1 The command name

          7.3.1.1 Invoking tag functions

          7.3.1.2 Invoking other functions

          7.3.1.3 Inserting the value of a variable

          7.3.1.4 Inserting a comment

        7.3.2 The Racket arguments

        7.3.3 The text argument

      7.4 Further reading

    8 Module reference

      8.1 Cache

      8.2 Decode

        8.2.1 Block

        8.2.2 Typography

      8.3 File

      8.4 Pagetree

        8.4.1 Navigation

        8.4.2 Utilities

      8.5 Render

      8.6 Template

      8.7 Tag

      8.8 Top

      8.9 World

    9 Acknowledgments

    10 License & source code

    Index

    ← prev  up  next → 
 
\ No newline at end of file +

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.

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.

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.

    1 Installation

    2 Quick tour

      2.1 Creating a source file

      2.2 Running a source file

      2.3 Naming, saving, and rendering a source file

      2.4 The project server

      2.5 Intermission

      2.6 Pollen as a preprocessor

      2.7 Markdown mode

      2.8 Markup mode

      2.9 Templates

      2.10 PS for Scribble users

      2.11 The end of the beginning

    3 Backstory

      3.1 Web development and its discontents

      3.2 The better idea: a programming model

      3.3 “Now you have two problems”

      3.4 Rethinking the solution for digital books

      3.5 Enter Racket

      3.6 What is Pollen?

    4 System overview

      4.1 The book is a program

      4.2 One language, multiple dialects

      4.3 Development environment

      4.4 A special data structure for HTML

      4.5 Pollen command syntax

      4.6 The preprocessor

      4.7 Templated source files

      4.8 Pagetrees

    5 Using raco pollen

      5.1 Making sure raco pollen works

      5.2 raco pollen

      5.3 raco pollen help

      5.4 raco pollen start

      5.5 raco pollen render

      5.6 raco pollen clone

    6 File formats

      6.1 Source formats

        6.1.1 Command syntax using ◊

        6.1.2 Any command is valid

        6.1.3 Standard exports

        6.1.4 Custom exports

        6.1.5 The project-require.rkt file

        6.1.6 Preprocessor (.pp extension)

        6.1.7 Markdown (.pmd extension)

        6.1.8 Markup (.pm extension)

        6.1.9 Pagetree (.ptree extension)

      6.2 Utility formats

        6.2.1 Scribble (.scrbl extension)

        6.2.2 Null (.p extension)

    7 ◊ command overview

      7.1 The golden rule

      7.2 The lozenge glyph (◊)

      7.3 The two command modes: text mode & Racket mode

        7.3.1 The command name

          7.3.1.1 Invoking tag functions

          7.3.1.2 Invoking other functions

          7.3.1.3 Inserting the value of a variable

          7.3.1.4 Inserting a comment

        7.3.2 The Racket arguments

        7.3.3 The text argument

      7.4 Further reading

    8 Module reference

      8.1 Cache

      8.2 Decode

        8.2.1 Block

        8.2.2 Typography

      8.3 File

      8.4 Pagetree

        8.4.1 Navigation

        8.4.2 Utilities

      8.5 Render

      8.6 Template

      8.7 Tag

      8.8 Top

      8.9 World

    9 Acknowledgments

    10 License & source code

    Index

    ← prev  up  next → 
 
\ No newline at end of file diff --git a/doc/manual-style.css b/doc/manual-style.css index a4bc28a..d9e1783 100644 --- a/doc/manual-style.css +++ b/doc/manual-style.css @@ -517,13 +517,10 @@ table.tocsublist { .toptoclink { font-weight: bold; - font-size: 110% -} - -/* hack to add space around .toptoclink because markup is all td */ -.toptoclink:after { - content: " "; - font-size: 3rem; + font-size: 110%; + margin-bottom: 0.5rem; + margin-top: 1.5rem; + display: inline-block; } .toclink { diff --git a/doc/racket.css b/doc/racket.css index 40a949e..b44fef5 100644 --- a/doc/racket.css +++ b/doc/racket.css @@ -144,9 +144,6 @@ .prototype td { vertical-align: text-top; } -.longprototype td { - vertical-align: bottom; -} .RktBlk { white-space: inherit; @@ -243,3 +240,10 @@ top: 0px; z-index: 1; } + +/* ---------------------------------------- */ +/* History */ + +.SHistory { + font-size: 82%; +} diff --git a/scribblings/system.scrbl b/scribblings/system.scrbl index 406222a..ec089a3 100644 --- a/scribblings/system.scrbl +++ b/scribblings/system.scrbl @@ -15,7 +15,7 @@ This is the core design principle of Pollen. Consistent with this principle, Pol @item{@bold{A Pollen project consists of source files + static files.} A @italic{source file} is a file that can be compiled to produce certain output. A @italic{static file} is usable as it stands (e.g., an SVG file or webfont). Generally, the textual content of your book will live in source files, and other elements will be static files.} -@item{@bold{Source control is a good idea.} Because Pollen projects are software projects, they can be easily managed with systems for source control and collaboration, like @link["http://github.com"]{GitHub}. If you're a writer at heart, don't fear these systems — they really do make revision & edit tracking easier than it is with Word or PDF files.} +@item{@bold{Source control is a good idea.} Because Pollen projects are software projects, they can be easily managed with systems for source control and collaboration, like @link["http://github.com"]{GitHub}. If you're a writer at heart, don't fear these systems — the learning curve is repaid by revision & edit tracking that's much easier than it is with Word or PDF files.} ] @@ -28,84 +28,110 @@ This is the core design principle of Pollen. Consistent with this principle, Pol @item{@bold{The Pollen language is based on Scribble.} Scribble is a variant of the Racket language that flips the usual programming syntax: instead of code with embedded textual content, a Scribble source file is text with embedded code (an idea borrowed from @link["https://en.wikipedia.org/wiki/TeX"]{TeX}). The Pollen language is adapted from Scribble. So most things that are true about Scribble are also true about Pollen (see @other-doc['(lib "scribblings/scribble/scribble.scrbl")]).} -@item{@bold{The Pollen language is divided into dialects.} The Pollen dialects share a common syntax and structure. But they're different in details that makes them better adapted to certain types of source files (for instance, one dialect of Pollen understands Markdown; the others don't). You can use whichever suits the task at hand.} +@item{@bold{The Pollen language is divided into dialects.} The Pollen dialects share a common syntax and structure. But they're different in details that makes them better adapted to certain types of source files (for instance, one dialect of Pollen understands Markdown; the others don't). Use whichever suits the task at hand.} ] @section{Development environment} -The Pollen development environment has two main pieces: the DrRacket code editor, and the Pollen project server. +The Pollen development environment has three main pieces: the DrRacket code editor, the project server, and the command-line tool. @itemlist[ -@item{@bold{Edit source files with DrRacket.} DrRacket is Racket's GUI code editor. Sure, you can also use a generic text editor. But DrRacket lets you immediately run your source file and see if it works. I know your favorite programming language doesn't have that. But trust me, it's very convenient.} +@item{@bold{Edit source files with DrRacket.} DrRacket is Racket's GUI code editor. Sure, you can also use a generic text editor. But DrRacket lets you immediately run your source and see if it works.} -@item{@bold{Render & preview web pages with the Pollen project server.} Pollen has a built-in development web server called the @italic{project server}. After you start the project server, you can preview & test your web pages within a web browser with maximum accuracy. Everything is rendered to static HTML so you can see exactly what you'll get.} +@item{@bold{Preview & test web pages with the Pollen project server.} Pollen has a built-in development web server called the @italic{project server}. After you start the project server, you can preview your web pages within any web browser, allowing you to test them with maximum accuracy.} -@item{@bold{One directory for everything.} Rather than separating your source files and static files, Pollen keeps them all in one directory so it's simple to make links between them.} +@item{@bold{Write the docs.} The project server can recognize and render Scribble files, so you can use it as a previewing tool while you're writing your documentation.} + +@item{@bold{Render & deploy from the command line.} Your Pollen project ultimately gets rendered to a set of static files (usually HTML and related assets). This can be controlled from the command line, so you can integrate it into other scripts.} -] +] @section{A special data structure for HTML} -X-expression +Unlike other programming languages, Pollen (and Racket) internally represent HTML with something called an @italic{X-expression}. An X-expression is simply a list that represents what in HTML is called an @italic{element}, meaning a thing with an opening tag, a closing tag, and content in between. Like HTML elements, X-expressions can be nested. Unlike HTML elements, X-expressions have no closing tag, they use parentheses to denote the start and end, and text elements are put inside quotes. -Tags can be tags +For example, consider this HTML element: -Or tags can be functions +@nested[#:style 'code-inset]{@verbatim{

Hello world

Nice to see you.

}} +As a Racket X-expression, this would be written: -@section{Preprocessor source files} +@nested[#:style 'code-inset]{@verbatim{(body (h1 "Hello world") (p "Nice to " (i "see") " you."))}} -Lower level of abstraction +More will be said about X-expressions. But a couple advantages should be evident already. First, without the redundant angle brackets, the X-expression is more readable than the equivalent HTML. Second, an X-expression is preferable to representing HTML as a simple string, because it preserves the internal structure of the element. -Work directly -Text output +@section{Pollen command syntax} -Any kind of file! +As mentioned above, a Pollen source file is not code with text embedded in it, but rather text with code embedded. (See @secref["reader"] for more.) +@itemlist[ -@section{Templated source files} +@item{@bold{If you can write text, you can program in Pollen.} Really. As you already found out in the @secref["quick-tour"], this is a valid Pollen program: +@racketmod[pollen +Hello world: how are you on this fine summer day?] +} + +@item{@bold{Commands start with ◊.} A simple rule: if a piece of text starts with @litchar{◊}, it's treated as a command; otherwise it's treated as ordinary text.} + +@item{@bold{Write commands in text mode or Racket mode.} Commands can use two equivalent notation systems: either Pollen's text-mode command syntax, or standard Racket syntax.} -Higher level of abstraction -Work indirectly +@item{@bold{Everything in Racket is in Pollen too.} This isn't some dimwit ``template language.'' Racket is a fully provisioned programming language, and every Racket function is available in Pollen.} -X-expression output +] -Markdown -Markup +@section{The preprocessor} -Templates +The @italic{preprocessor} is the simplest processing mode in Pollen. -@section{Utility source files} +@itemlist[ -Scribble +@item{@bold{Text output.} The preprocessor scans the source for any Pollen commands, resolves them, and outputs the whole file as text.} -Null +@item{@bold{Work with any text file.} I hope this blows your mind a teeny bit. You can use the preprocessor with HTML, CSS, Markdown, JavaScript, XML, SVG, or any other text-based file (including source files of other programming languages).} +@item{@bold{Start quickly.} Because it works with any text file, the preprocessor is an easy way to try out Pollen, because you can mix it into your workflow on an existing project, or even just one file.} -@section{Pagetrees} +] -Navigation +@section{Templated source files} -Hierarchy +If you want to apply a particular page format to multiple sources of content — as you would in a book — you can use Pollen @italic{templates}. -Subsetting +@itemlist[ -Build script +@item{@bold{Templates can be any format.} Usually Pollen templates will be HTML. But they don't have to be.} +@item{@bold{Markdown support.} Pollen has a built-in Markdown parser, so you can import Markdown sources into a Pollen publication.} +@item{@bold{Custom markup.} Pollen's markup mode allows you the freedom to define your own markup tags and attach behavior to them.} +@item{@bold{Mix source types.} Every text source is converted to an X-expression before going into a template. So it's fine to have multiple kinds of text source in one project.} +] + + + +@section{Pagetrees} + +Similar to a table of contents, a @italic{pagetree} is a special Pollen source file that gets turned into a hierarchical list of pages. + + +@itemlist[ + +@item{@bold{Navigation.} Pagetrees are used to provide navigation links within HTML templates (like previous, next, up, top).} + +@item{@bold{Organization.} Multiple pagetrees can be used to divide your project into subsets of pages that should be treated separately.} + + +] -@section{Build & deploy} -Pollen is not a production server -Render & clone \ No newline at end of file