#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 "scribble-helpers.rkt")

@(require (for-label "../pollen.rkt"
                     "../dust.rkt"
                     "../snippets-html.rkt"
                     racket/base
                     racket/contract
                     racket/string
                     pollen/template
                     pollen/pagetree
                     txexpr
                     sugar/coerce))

@title{@filepath{snippets-html.rkt}}

@defmodule["snippets-html.rkt" #:packages ()]

Each “snippet” module provides all the document- and article-level blocks of structural markup
necessary for a particular target output format; this one is for HTML. The idea is that any block of
markup that might be reused across more than one template should be a function.

The functions in the snippets modules follow two conventions in this project:

@itemlist[
  @item{Functions that return strings of HTML have the prefix @tt{html$-}.}
  @item{Such functions do not do any parsing or destructuring of complex objects; every separate
  piece that will be inserted into the template is passed in as a separate argument. This makes it
  harder to change the scope of what a snippet does, but makes things faster since all the parsing
  can happen in one place, before the snippet functions are called.} ]

@section{Using @tt{pollen/mode}}

It’s worth looking at the source for this file to see how @racketmodname[pollen/mode] can be used to
make it easy to write “mini-template” functions:

@codeblock{
#lang pollen/mode racket/base

(define (html$-my-article title body-tx)
  ◊string-append{
    <p><b>◊|title|</b><p>
    ◊(->html body-tx)
  })
}

@section{HTML Snippet functions}

@defproc[(html$-page-head [title (or/c string? #f) #f]) non-empty-string?]

Returns the @tt{<head>} section of an HTML document.

@defproc[(html$-page-body-open) non-empty-string?]

Returns the opening @tt{<body>} and @tt{<main>} tags and elements that immediately follow, such as
site header, logo and navigation.

@defproc[(html$-article-open [pagenode pagenode?] 
                             [title-specified-in-doc? boolean?] 
                             [title txexpr?] 
                             [pubdate string?])
          non-empty-string?]

Returns the opening @tt{<article>} tag and elements that immediately follow: permlink, publish date,
and opening @tt{<section>} tag.

The @racket[_title-specified-in-doc?] form changes the HTML markup structure used.

@defproc[(html$-article-close [footertext string?]) non-empty-string?]

Returns a string containing a closing @tt{<section>} tag, a @tt{<footer>} element containing
@racket[_footertext], and a closing @tt{<article>} tag. If @racket[_footertext] is empty, the
@tt{<footer>} element will be omitted.

@defproc[(html$-article-listing-short [pagenode pagenode?] [pubdate string?] [title string?])
non-empty-string?]

Returns a string of HTML for an article as it would appear in a listing context in “short” form
(date and title only, with link).

@defproc[(html$-page-body-close) non-empty-string?]

Returns a string containing the page’s @tt{<footer>} and closing tags.

@defproc[(html$-note-title [author string?] [pagenode pagenode?] [parent-title string?])
non-empty-string?]

Returns a string containing the HTML for a note’s title. The title is used when the note is
displayed in a separate context from its parent article.

If @racket[_author] is empty, then @racket[default-authorname] is used. The @racket[_pagenode] and
@racket[_parent-title] values are for generating a link to the parent article.

@defproc[(html$-note-contents [disposition-mark string?] [elems (listof xexpr?)]) non-empty-string?]

Returns a string containing the body-elements of a note converted to HTML. If
@racket[_disposition-mark] is not empty, a @tt{<span>} containing it will be inserted as the first
element of the first block-level element.

@defproc[(html$-note-listing-full [pagenode pagenode?]
                                  [note-id string?] 
                                  [title-html-flow string?]
                                  [date string?]
                                  [contents string?] 
                                  [author string? (default-authorname)] 
                                  [author-url string? ""])
          non-empty-string?]

Returns a string containing the complete HTML markup for a @racket[note], including title, permlink,
date, contents and author, suitable for display outside the context of its parent article.

@defproc[(html$-note-in-article [id string?] 
                                [date string?] 
                                [contents string?] 
                                [author string?]
                                [author-url string?]) non-empty-string?]

Like @racket[html$-note-listing-full], but returns HTML for a @racket[note] suitable for display
inside its parent article.

@defproc[(html$-notes-section [note-htmls string?]) non-empty-string?]

Returns the complete HTML for the @italic{Further Notes} section of an article.


