#lang scribble/manual

@; Copyright (c) 2019 Joel Dueck
@;
@; Copying and distribution of this file, with or without modification,
@; are permitted in any medium without royalty provided the copyright
@; notice and this notice are preserved.  This file is offered as-is,
@; without any warranty.

@(require (for-label "../pollen.rkt"
                     txexpr
                     pollen/tag
                     pollen/setup))

@title{@filepath{pollen.rkt}}

@author{Joel Dueck}

@defmodule["pollen.rkt" #:packages ()]

The file @filepath{pollen.rkt} is implicitly @code{require}d in every template and every @code{#lang pollen} file in the project. It defines the markup for all Pollen documents, and also re-provides everything provided by @code{crystalize.rkt}.

The @code{setup} module towards the top of the file is used as described in @racketmodname[pollen/setup].

@section{Defining new tags}

I use a couple of macros to define tag functions that automatically branch into other functions depending on the current output target format. This allows me to put the format-specific tag functions in separate files that have separate places in the dependency chain. So if only the HTML tag functions have changed and not those for PDF, the makefile can ensure only the HTML files are rebuilt.

@defproc[#:kind "syntax"
 (poly-branch-tag (id symbol?))
 (-> txexpr?)]
Define a new tag function (using @racket[define-tag-function]) for @racket[_id], which will automatically pass all of its attributes and elements to a tag function whose name is the value returned by @racket[current-poly-target], followed by a hyphen, followed by @racket[_id]. So whenever the current output format is @racket['html], the function defined by @racket[(poly-branch-tag _p)] will branch to a function named @racket[html-p]; when the current format is @racket['pdf], it will branch to @racket[pdf-p], and so forth.

You @emph{must} define these branch functions separately, and you must define one for @emph{every} output format included in the definition of @racket[poly-targets] in this file’s @racket[setup] submodule. If you do not, you will get “unbound identifier” errors at expansion time.

The convention in this project is to define and provide these branch functions in separate files: see, e.g., @filepath{tags-html.rkt}.

@defproc[#:kind "syntax"
         (poly-branch-func (id symbol?))
         (-> txexpr?)]

Like @racket[poly-branch-tag], but uses @racket[define] instead of @racket[define-tag-function].