◊(Local Yarn Code "Check-in [8e0002ee]")

Login
About History Code Code Docs Road Map Issues
Overview
Comment:Add scribble docs for snippets-html
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 8e0002ee88d1d62477d6252d590e8bd030c6e568f3f5ddfea53cd56b0134b452
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
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Modified code-docs/main.scrbl from [f7a55451] to [9028aeca].

︙
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



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.
wiki for anything else.


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

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.













This page was generated in about
0.012s by
Fossil 2.19 [318ab802db] 2022-05-27 02:05:21