14.5 Pagetree

Books and other long documents are usually organized in a structured way — at minimum they have a sequence of pages, but more often they have sections with subsequences within. Individual pages in a Pollen project don’t know anything about how they’re connected to other pages. In theory, you could maintain this information within the source files. But this would be a poor use of human energy.

Instead, use a pagetree. A pagetree is a simple abstraction for defining & working with sequences of pagenodes. Typically these pagenodes will be the names of output files in your project.

“So it’s a list of web-page filenames?” Sort of. When I think of a web page, I think of an actual file on a disk. Keeping with Pollen’s orientation toward dynamic rendering, pagenodes may — and often do — refer to files that don’t yet exist. Moreover, by referring to output names rather than source names, you retain the flexibility to change the kind of source associated with a particular pagenode (e.g., from preprocessor source to Pollen markup).

Pagetrees can be flat or hierarchical. A flat pagetree is just a list of pagenodes. A hierarchical pagetree can also contain recursively nested lists of pagenodes. But you needn’t pay attention to this distinction, as the pagetree functions don’t care which kind you use. Neither do I.

Pagetrees surface throughout the Pollen system. They’re primarily used for navigation — for instance, calculating “previous,” “next,” or “up” links for a given page. A special pagetree, "index.ptree", is used by the project server to order the files in a dashboard. Pagetrees can also be used to define batches of files for certain operations, for instance raco pollen render. You might find other uses for them too.

14.5.1 Making pagetrees with a source file

A pagetree source file either starts with #lang pollen and uses the .ptree extension, or starts with #lang pollen/ptree and then can have any file extension.

Unlike other Pollen source files, since the pagetree source is not rendered into an output format, the rest of the filename is up to you.

Here’s a flat pagetree. Each line is considered a single pagenode (blank lines are ignored). Notice that no Pollen command syntax nor quoting is needed within the pagetree source:

And here’s the output in DrRacket:

'(pagetree-root index.html introduction.html main_argument.html conclusion.html)

Keeping with usual Pollen policy, this is an X-expression. The pagetree-root is just an arbitrary tag that contains the pagetree.

Upgrading to a hierarchical pagetree is simple. The same basic rule applies — one pagenode per line. But this time, you add Pollen command syntax: a lozenge ◊ in front of a pagenode marks it as the top of a nested list, and the sub-pagenodes of that list go between { curly braces }, like so:

The output of our hierarchical pagetree:

'(pagetree-root toc.html (first-chapter.html foreword.html introduction.html) (second-chapter.html (main-argument.html facts.html analysis.html) conclusion.html) bibliography.html)

One advantage of using a source file is that when you run it in DrRacket, it will automatically be checked using validate-pagetree, which insures that every element in the pagetree meets pagenode?, and that all the pagenodes are unique.

This pagetree has a duplicate pagenode, so it won’t run:

Instead, you’ll get an error:

validate-pagetree: members-unique? failed because item isn’t unique: (index.html)

Pagenodes can refer to files in subdirectories. Just write the pagenode as a path relative to the directory where the pagetree lives:

14.5.2 Making pagetrees by hand

Because a pagetree is just an X-expression, you can synthesize a pagetree using any Pollen or Racket tools for making X-expressions. For example, here’s some Racket code that generates the same pagetree as the "flat.ptree" source file above:

Note that you need to take more care when building a pagetree by hand. Pagenodes are symbols, not strings, thus the use of string->symbol is mandatory. One benefit of using a pagetree source file is that it takes care of this housekeeping for you.

14.5.3 Nesting pagetrees

You can put other pagetrees within a pagetree. Since every pagetree is an X-expression, you can nest pagetrees as you would ordinary X-expressions. Suppose you have this pagetree:

And you want to add it to an existing pagetree:

You can require "sub.ptree" to import its doc. Be sure to use prefix-in so that the imported doc ends up with a distinct name that doesn’t conflict with the doc that’s already part of the current file:

And you’ll get this:

'(pagetree-root one two three four five six)

Pollen does one bit of housekeeping for you, which is that it automatically drops the root node of the imported pagetree, and splices the remaining nodes into the parent pagetree at the insertion point. Otherwise you’d get this, which is probably not what you wanted:

'(pagetree-root one two (pagetree-root three four) five six)

But if you do want the imported pagetree under a subnode, just add a containing pagenode as usual:

Which will give you:

'(pagetree-root one two (subtree three four) five six)

If you want to combine a number of pagetrees, require can get cumbersome because you have to juggle multiple doc imports (which can be done with prefix-in, but it’s still juggling). Instead, you can use dynamic-require to put each imported pagetree where you want it.

Nesting pagetrees won’t circumvent the usual rule against duplicate pagenodes. So this pagetree, which tries to nest "sub.ptree" twice, won’t work:

14.5.4 The automatic pagetree

In situations where Pollen needs a pagetree but can’t find one, it will automatically synthesize a pagetree from a listing of files in the directory. This arises most frequently when The project dashboard in a directory that doesn’t contain an explicit "index.ptree". This way, you can get going with a project without having to stop for .ptree housekeeping.

As usual, convenience has a cost. Pollen doesn’t know anything about which files in your directory are relevant to the project, so it includes all of them. For instance, if you start your project server on a Mac OS desktop, you’ll see things like "Thumbs.db" and "desktop.ini".

Also, though you can use pagetree-navigation functions like next or siblings with an automatic pagetree, the results of these functions are apt to include irrelevant files. So if you need to do pagetree navigation, that’s probably the point where you want to start using an explicit pagetree.

14.5.5 Using pagetrees for navigation

Typically you’ll call the pagetree-navigation functions from inside templates, using the special variable here as the starting point. For more on this technique, see Pagetree navigation.

14.5.6 Using "index.ptree" in the dashboard

When you’re using the project server to view the files in a directory, the server will first look for a file called "index.ptree". If it finds this pagetree file, it will use it to build the dashboard. If not, then it will synthesize a pagetree using a directory listing. For more on this technique, see The project dashboard.

14.5.7 Using pagetrees with raco pollen render

The raco pollen render command is used to regenerate an output file from its source. If you pass a pagetree to raco pollen render, it will automatically render each file listed in the pagetree.

For instance, many projects have auxiliary pages that don’t really belong in the main navigational flow. You can collect these pages in a separate pagetree:

Thus, when you’re using pagetree-navigation functions within a template, you can use your main pagetree, and restrict the navigation to the main editorial content. But when you render the project, you can pass both pagetrees to raco pollen render.

For more on this technique, see raco pollen render.

14.5.8 Functions

14.5.8.1 Predicates & validation

Pagenodes are symbols (rather than strings) so that pagetrees will be valid tagged X-expressions, which is a more convenient format for validation & processing.

14.5.8.2 Navigation

14.5.8.3 Utilities