Index: code-docs/snippets-html.scrbl
==================================================================
--- code-docs/snippets-html.scrbl
+++ code-docs/snippets-html.scrbl
@@ -14,17 +14,17 @@
pollen/template
pollen/pagetree
txexpr
sugar/coerce))
-@title{@filepath{snippets-html.rkt}}
+@title{HTML snippets}
@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.
+Each “snippet” module provides all (well @emph{most of}) 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$-}.}
@@ -48,91 +48,114 @@
})
}
@section{HTML Snippet functions}
-@defproc[(html$-page-head [title (or/c string? #f) #f] [close-head? boolean? #t]) non-empty-string?]
+@defproc[(html$-page-head [title (or/c string? #f) #f] [close-head? boolean? #t])
+non-empty-string?]{
-Returns the @tt{} section of an HTML document.
+Returns the @tt{} section of an HTML document.
If @racket[_title] is a string it will be used inside the @tt{} tag.
If you want to include additional stuff inside the @tt{<head>}, you can set @racket[_close-head?] to
@racket[#f] to prevent it from including the closing @tt{</head>} tag (you’ll have to add it
yourself).
+}
-@defproc[(html$-page-body-open [body-class string? ""]) non-empty-string?]
+@defproc[(html$-page-body-open [body-class string? ""]) non-empty-string?]{
Returns the opening @tt{<body>} and @tt{<main>} tags and elements that immediately follow, such as
site header, logo and navigation.
If @racket[_body-class] is a non-empty string, its contents will be included in the @tt{class}
attribute of the @tt{<body>} tag.
+}
+
+@defproc[(html$-series-list) non-empty-string?]{
+
+Returns an HTML @tt{<section>} containing a list of all series, grouped by their “plural nouns”. The
+grouped list will flow into columns on wider displays.
+}
@defproc[(html$-article-open [pagenode pagenode?]
[title-specified-in-doc? boolean?]
[title txexpr?]
[pubdate string?])
- non-empty-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?]
+@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?]
+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-footer) non-empty-string?]{
+Returns an HTML @tt{<footer>} tag for use at the bottom of each page.
+}
-@defproc[(html$-page-body-close) non-empty-string?]
+@defproc[(html$-page-body-close) non-empty-string?]{
Returns a string containing the page’s @tt{<footer>} and closing tags.
+}
-@defproc[(html$-note-contents [disposition-mark string?] [elems (listof xexpr?)]) non-empty-string?]
+@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?]
+ 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?]
+ [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?]
+@defproc[(html$-notes-section [note-htmls string?]) non-empty-string?]{
Returns the complete HTML for the @italic{Further Notes} section of an article.
+}
@defproc[(html$-paginate-navlinks [current-page exact-positive-integer?]
[pagecount exact-positive-integer?]
- [basename string?]) string?]
+ [basename string?]) string?]{
On the “blog”, the articles are split across multiple files: @filepath{blog-pg1.html},
@filepath{blog-pg2.html}, etc. This function provides a string containing HTML for a group of links
that can be given within each file, to link to the pages that come before/after it.
The links are enclosed within @tt{<li>} tags. It’s up to the calling site to provide the enclosing
@tt{<ul>} tag (in case any custom styling or IDs need to be applied).
+}