Overview
| Comment: | Add scribble docs for snippets-html |
|---|---|
| Timelines: | family | ancestors | descendants | both | trunk |
| Files: | files | file ages | folders |
| SHA3-256: |
8e0002ee88d1d62477d6252d590e8bd0 |
| User & Date: | joel on 2019-02-23 23:16:06 |
| Other Links: | manifest | tags |
Context
|
2019-03-03
| ||
| 21:34 | More code docs check-in: a4190d26 user: joel tags: trunk | |
|
2019-02-23
| ||
| 23:16 | Add scribble docs for snippets-html check-in: 8e0002ee user: joel tags: trunk | |
| 23:15 | Small fixes and improvements to HTML snippet functions check-in: 95725823 user: joel tags: trunk | |
Changes
Modified code-docs/main.scrbl from [f7a55451] to [9028aeca].
| ︙ | ︙ | |||
13 14 15 16 17 18 19 |
@title{Local Yarn: source code notes}
@author{Joel Dueck}
These are my notes about the internals of the Local Yarn source code. In other words, a personal
reference, rather than a tutorial. These pages concern only the source code itself. Refer to the
| > | > > | 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
@title{Local Yarn: source code notes}
@author{Joel Dueck}
These are my notes about the internals of the Local Yarn source code. In other words, a personal
reference, rather than a tutorial. These pages concern only the source code itself. Refer to the
wiki for info about deployment, etc.
You’ll get the most out of these notes if you have read @other-doc['(lib
"pollen/scribblings/pollen.scrbl")], and worked through the tutorials by hand.
If you’re viewing these notes on the Fossil repository, note that these pages are heavily
interlinked with the central Racket documentation at @tt{docs.racket-lang.org}, which are written
and maintained by others. Links on those pages that lead outside of that domain will not work within
this repo’s “Code Docs” frame, due to the repository’s
@ext-link["https://content-security-policy.com"]{content security policy}. To follow such links,
right-click and open the link in a new tab or window.
@local-table-of-contents[]
@include-section["pollen.scrbl"] @; pollen.rkt
@include-section["dust.scrbl"] @; dust.rkt
@include-section["sqlite-tools.scrbl"] @; sqlite-tools.rkt
@include-section["snippets-html.scrbl"] @; you get the idea
|
Modified code-docs/pollen.scrbl from [85e2b6f4] to [dd25189e].
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
#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"
racket/base
txexpr
pollen/tag
pollen/setup
pollen/core
sugar/coerce))
@title[#:tag "pollen-rkt"]{@filepath{pollen.rkt}}
| > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
#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"
racket/base
racket/contract
racket/string
txexpr
pollen/tag
pollen/setup
pollen/core
sugar/coerce))
@title[#:tag "pollen-rkt"]{@filepath{pollen.rkt}}
|
| ︙ | ︙ |
Added code-docs/snippets-html.scrbl version [a2ab701d].
> > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 |
#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
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 [title? boolean?] [title-html-flow string?] [pubdate string?])
non-empty-string?]
Returns the opening @tt{<article>} tag and elements that immediately follow: permlink, publish date,
and opening @tt{<section>} tag.
This function could be smarter, but for now @racket[_title?] determines which HTML markup structure
to use for the article regardless of whether @racket[_title-html-flow] is empty or not.
@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$-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.
|