◊(Local Yarn Code "series.scrbl at [5cdf3aa9]")

File code-docs/series.scrbl artifact 09dae3f6 part of check-in 5cdf3aa9

#lang scribble/manual

@; SPDX-License-Identifier: BlueOak-1.0.0
@; This file is licensed under the Blue Oak Model License 1.0.0.

@(require "scribble-helpers.rkt"
          scribble/example)

@(require (for-label "../pollen.rkt"
                     "../series-list.rkt"
                     "../dust.rkt"
                     "../cache.rkt"
                     pollen/core
                     racket/base
                     racket/contract))

@title{Defining Series}

To create a new series:

@itemlist[#:style 'ordered

  @item{Create a file @filepath{my-key.poly.pm} inside @racket[series-folder] and include a call
  to @racket[fenced-listing] to list all the articles and notes that will be included in the series:
  @codeblock|{
#lang pollen

◊(define-meta title "My New Series")

◊block{Here’s what we call a bunch of similar articles:

◊(fenced-listing (articles 'short))

}
  }|
  }
  
  @item{Add an entry for @racket[_my-key] to @racket[series-list] in @filepath{series-list.rkt}}

  @item{Use @racket[(define-meta series "my-key")] in articles to add them to the series.}

  @item{If @racket[series-ptree-ordered?] is @racket[#t], create a @seclink["Pagetree" #:doc '(lib
  "pollen/scribblings/pollen.scrbl")]{pagetree} file in @racket[series-folder] named
  @filepath{my-key.ptree}.}

  ]

@section{Series list}

@defmodule["series-list.rkt" #:packages ()]

This module contains the most commonly used bits of meta-info about @tech{series}. Storing these
bits in a hash table of structs makes them faster to retrieve than when they are stored inside the
metas of the Pollen documents for the series themselves.

@defthing[series-list hash?]{

An immutable hash containing all the title and noun info for each @tech{series}. Each key is
a string and each value is a @racket[series] struct.

}

@defstruct[series ([key            string?]
                   [title          string?]
                   [noun-plural    string?]
                   [noun-singular  string?]
                   [ptree-ordered? boolean?])]{

Struct for holding metadata for a @tech{series}. The @racket[_ptree-ordered?] value should be
@racket[#t] if there is a @filepath{@italic{key}.ptree} file in @racket[series-folder] that provides
information on how articles in the series are ordered.

}